feat: add validated collector contracts, lifecycle coordination, and isolated typed snapshot capture for adapters. (#4)

Author: terabytesoftw

.github/workflows/build.yml

@@ -22,5 +22,5 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     with:
       concurrency-group: phpunit-${{ github.workflow }}-${{ github.ref }}
-      extensions: mbstring
+      extensions: intl, mbstring
       php-version: '["8.3","8.4","8.5"]'

CHANGELOG.md

@@ -10,3 +10,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - feat: add framework-agnostic debug snapshot contracts, strict JSON hydration, and filesystem persistence.
 - fix: bundle toolbar control icons and retry snapshot data while Yii3 finishes its post-response persistence.
 - feat: add shared framework-neutral normalization and presentation helpers for debug adapters.
+- feat: add validated collector contracts, lifecycle coordination, and isolated typed snapshot capture for adapters.

README.md

@@ -16,11 +16,11 @@ composer require php-forge/debug-core
 
 ## Architecture
 
-The core package owns portable debug data, persistence, normalization and presentation primitives under
-`PHPForge\Debug\Helper`, the frontend source and compiled files, shared fonts and icons, the toolbar data contract, and
-framework-neutral PHP templates composed with the agnostic UI Awesome HTML helpers. It does not register assets,
-render responses, inject toolbar markup, or depend on Yii2, Yii3, an application container, a view implementation, or
-a framework request lifecycle.
+The core package owns portable collector contracts and coordination, debug data, persistence, normalization and
+presentation primitives under `PHPForge\Debug\Helper`, the frontend source and compiled files, shared fonts and icons,
+the toolbar data contract, and framework-neutral PHP templates composed with the agnostic UI Awesome HTML helpers. It
+does not register assets, render responses, inject toolbar markup, or depend on Yii2, Yii3, an application container, a
+view implementation, or a framework request lifecycle.
 
 Adapters collect framework data, convert it into immutable snapshots, expose toolbar data endpoints, define and
 publish assets through their framework, and render the shared templates with their framework view component. They also

composer-require-checker.json

@@ -1,5 +1,8 @@
 {
-    "symbol-whitelist": [],
+    "symbol-whitelist": [
+        "posix_getpwuid",
+        "posix_getuid"
+    ],
     "php-core-extensions": [
         "Core",
         "date",

composer.json

@@ -20,8 +20,11 @@
     ],
     "require": {
         "php": ">=8.3",
+        "ext-ctype": "*",
+        "ext-intl": "*",
         "ext-mbstring": "*",
         "ui-awesome/html": "^0.6",
+        "ui-awesome/html-helper": "^0.7",
         "ui-awesome/html-svg": "^0.6"
     },
     "require-dev": {

resources/assets/dist/css/debug.min.css

@@ -588,15 +588,47 @@
   }
 
   /**
-   * Hero block at the top of the Request panel — verb + URL + status + meta line.
-   * Reuses the snapshot status pill so colors stay consistent with the sidebar card.
+   * Request overview — a continuous telemetry rail for identity, response,
+   * runtime metrics, and capture metadata.
    */
-  .yii-debug-request-hero {
+  .yii-debug-request-overview {
+    overflow: hidden;
     margin-bottom: var(--yii-debug-space-4);
-    padding: var(--yii-debug-space-3) var(--yii-debug-space-4);
     border: var(--yii-debug-border);
-    border-radius: var(--yii-debug-radius-md);
-    background: var(--yii-debug-panel-surface-muted);
+    border-inline-start: 4px solid
+      color-mix(
+        in srgb,
+        var(--yii-debug-hue, var(--yii-debug-panel-muted)) 76%,
+        var(--yii-debug-panel-text)
+      );
+    border-radius: var(--yii-debug-radius-lg);
+    background: var(--yii-debug-panel-surface);
+    box-shadow: var(--yii-debug-shadow-sm);
+  }
+
+  .yii-debug-request-overview-header {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: var(--yii-debug-space-4);
+    align-items: center;
+    padding: var(--yii-debug-space-4);
+  }
+
+  .yii-debug-request-overview-identity {
+    min-width: 0;
+  }
+
+  .yii-debug-request-overview-label,
+  .yii-debug-request-overview-status-label,
+  .yii-debug-panel-heading-eyebrow {
+    display: block;
+    margin-bottom: 5px;
+    color: var(--yii-debug-panel-muted);
+    font-size: 0.6875rem;
+    font-weight: 700;
+    letter-spacing: 0.09em;
+    line-height: 1.2;
+    text-transform: uppercase;
   }
 
   .yii-debug-request-hero-line {
@@ -626,16 +658,183 @@
     white-space: nowrap;
   }
 
-  .yii-debug-request-hero-meta {
+  .yii-debug-request-overview-status {
+    min-width: 72px;
+    text-align: right;
+  }
+
+  .yii-debug-request-overview-status-value {
+    padding: 3px 9px;
+    font-family: var(--yii-debug-font-mono);
+    font-size: var(--yii-debug-fs-lg);
+    letter-spacing: -0.03em;
+    line-height: 1.2;
+  }
+
+  .yii-debug-request-overview-metrics {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    margin: 0;
+    border-block: var(--yii-debug-border);
+    background: var(--yii-debug-panel-surface-muted);
+  }
+
+  .yii-debug-request-overview-metric {
+    min-width: 0;
+    padding: var(--yii-debug-space-3) var(--yii-debug-space-4);
+
+    & + & {
+      border-inline-start: var(--yii-debug-border);
+    }
+
+    dt {
+      margin-bottom: 2px;
+      color: var(--yii-debug-panel-muted);
+      font-size: 0.6875rem;
+      font-weight: 700;
+      letter-spacing: 0.07em;
+      text-transform: uppercase;
+    }
+
+    dd {
+      overflow: hidden;
+      margin: 0;
+      color: var(--yii-debug-panel-text);
+      font-family: var(--yii-debug-font-mono);
+      font-size: var(--yii-debug-fs-sm);
+      font-weight: 600;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+  }
+
+  .yii-debug-request-overview-meta {
     display: flex;
     flex-wrap: wrap;
-    gap: 6px var(--yii-debug-space-3);
-    margin-top: 6px;
+    align-items: center;
+    gap: var(--yii-debug-space-2) var(--yii-debug-space-4);
+    padding: 10px var(--yii-debug-space-4);
     color: var(--yii-debug-panel-muted);
     font-family: var(--yii-debug-font-mono);
     font-size: var(--yii-debug-fs-xs);
   }
 
+  .yii-debug-request-overview-meta-item {
+    display: inline-flex;
+    min-width: 0;
+    align-items: baseline;
+    gap: 6px;
+  }
+
+  .yii-debug-request-overview-meta-label {
+    color: var(--yii-debug-panel-muted);
+    font-family: var(--yii-debug-font-sans);
+    font-size: 0.625rem;
+    font-weight: 700;
+    letter-spacing: 0.07em;
+    text-transform: uppercase;
+  }
+
+  .yii-debug-request-overview-tag {
+    overflow: hidden;
+    max-width: 34ch;
+    color: var(--yii-debug-panel-text);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .yii-debug-request-overview-flag,
+  .yii-debug-panel-heading-kind {
+    padding: 2px 8px;
+    border: var(--yii-debug-border);
+    border-radius: var(--yii-debug-radius-pill);
+    background: var(--yii-debug-panel-pill);
+    color: var(--yii-debug-panel-muted);
+    font-family: var(--yii-debug-font-mono);
+    font-size: 0.625rem;
+    font-weight: 700;
+    letter-spacing: 0.07em;
+    line-height: 1.4;
+    text-transform: uppercase;
+  }
+
+  .yii-debug-panel-heading {
+    display: flex;
+    align-items: flex-end;
+    justify-content: space-between;
+    gap: var(--yii-debug-space-3);
+    margin: var(--yii-debug-space-5) 0 var(--yii-debug-space-3);
+    padding-bottom: var(--yii-debug-space-2);
+    border-bottom: var(--yii-debug-border);
+  }
+
+  .yii-debug-panel-heading-copy {
+    min-width: 0;
+
+    h2 {
+      margin: 0;
+    }
+  }
+
+  .yii-debug-panel-heading-kind {
+    flex: none;
+    margin-bottom: 2px;
+  }
+
+  pre.yii-debug-panel-payload {
+    min-height: 180px;
+    margin-bottom: 0;
+    padding: var(--yii-debug-space-4);
+    border: var(--yii-debug-border);
+    background:
+      linear-gradient(
+        90deg,
+        color-mix(
+          in srgb,
+          var(--yii-debug-panel-primary),
+          transparent 88%
+        ),
+        transparent 42%
+      ),
+      var(--yii-debug-panel-code-bg);
+    line-height: 1.55;
+  }
+
+  @media (width <= 640px) {
+    .yii-debug-request-overview-header {
+      grid-template-columns: minmax(0, 1fr);
+      gap: var(--yii-debug-space-3);
+    }
+
+    .yii-debug-request-overview-status {
+      display: flex;
+      align-items: center;
+      gap: var(--yii-debug-space-2);
+      text-align: left;
+    }
+
+    .yii-debug-request-overview-status-label {
+      margin: 0;
+    }
+
+    .yii-debug-request-overview-metrics {
+      grid-template-columns: 1fr;
+    }
+
+    .yii-debug-request-overview-metric + .yii-debug-request-overview-metric {
+      border-block-start: var(--yii-debug-border);
+      border-inline-start: 0;
+    }
+
+    .yii-debug-request-overview-meta-item {
+      width: 100%;
+    }
+
+    .yii-debug-panel-heading {
+      align-items: flex-start;
+    }
+  }
+
   /**
    * Inline section header used by tabular blocks; pairs the title with an
    * optional filter input on the right.