The design language that makes your AI harness better at design.
JavaScript
//! Native static-entry adapter. One immutable snapshot; batches share a browser per viewport.
use crate::{
asset_capture::CdpAssetRenderer,
capture_snapshot::{HtmlSnapshot, SnapshotSelection},
component_capture::render_page,
};
use impeccable_browser::{cdp::Browser, discovery, html_snapshot::HtmlSnapshot as PageSnapshot};
use impeccable_comp_verbs::asset_capture::capture_sha256;
use impeccable_comp_verbs::entry_capture::{
CapturedEntry, EntryEvidence, EntryRenderer, EntryRequest, EntryStage, FrameEvidence,
};
use serde_json::{Value, json};
use std::{
collections::BTreeMap,
fs,
path::{Path, PathBuf},
sync::Arc,
};
pub struct CdpEntryRenderer;
/// Largest share of a frame that images may cover when the spec declares no
/// raster region. Logos, avatars and icons sit well under it (a 200x60 logo is
/// about 1% of a 1440x900 viewport; a row of twelve 40px avatars under 2%); a
/// chart, photo or copied comp that carries real weight in the comparison sits
/// well over it. A spec with raster regions gets the same limit for what images
/// paint outside those regions.
pub const TEXT_ONLY_RASTER_SHARE_MAX: f64 = 0.15;
/// The frozen inputs a capture was drawn from. A text-only capture also binds
/// the hero review manifest whose dependency list chose what the page may load.
struct FrozenEntry {
snapshot: Arc<HtmlSnapshot>,
manifest: Option<(PathBuf, Vec<u8>)>,
evidence: EntryEvidence,
}
impl CapturedEntry for FrozenEntry {
fn evidence(&self) -> &EntryEvidence {
&self.evidence
}
fn verify_current(&self) -> Result<(), String> {
self.snapshot.verify_current()?;
if let Some((path, bytes)) = &self.manifest {
if fs::read(path).ok().as_ref() != Some(bytes) {
return Err("capture input changed: .impeccable/review/hero.json".into());
}
}
Ok(())
}
}
impl EntryRenderer for CdpEntryRenderer {
fn capture_entry(&self, request: &EntryRequest) -> Result<Box<dyn CapturedEntry>, String> {
self.capture_forbidding(request, &[])
}
}
/// The instant a capture's clock is pinned to, and where it came from.
#[derive(Clone, Copy)]
pub struct CaptureClock {
pub epoch_ms: f64,
/// True when the instant is the one an approved review screenshot was captured at.
pub from_review: bool,
}
impl CaptureClock {
pub fn now() -> Self {
Self { epoch_ms: crate::component_capture::now_ms(), from_review: false }
}
fn json(&self) -> Value {
json!({"pinnedEpochMs": self.epoch_ms.floor() as i64, "source": if self.from_review { "approved-review" } else { "capture-start" },
"policy": "every frame's Date starts at the pinned instant and advances in real time"})
}
}
impl CdpEntryRenderer {
/// `forbidden` holds approved images (a reviewed screenshot) that the page
/// must not load or embed; the bound comp is always forbidden.
pub fn capture_forbidding(
&self,
request: &EntryRequest,
forbidden: &[&[u8]],
) -> Result<Box<dyn CapturedEntry>, String> {
self.capture_at(request, forbidden, CaptureClock::now())
}
/// As [`Self::capture_forbidding`], with every frame's clock pinned to `clock`:
/// a page that renders the time or day shows the same state in each frame,
/// and the same state as an approved screenshot captured at that instant.
pub fn capture_at(
&self,
request: &EntryRequest,
forbidden: &[&[u8]],
clock: CaptureClock,
) -> Result<Box<dyn CapturedEntry>, String> {
// The shared gate chooses the entry/spec/reference, never a caller URL.
// Spec and comp are bound (hashed and re-verified) but never served: a
// page graded against the comp must not be able to show it.
let inventory = static_inventory(&request.root)?;
let served: Vec<String> = inventory
.iter()
.filter(|p| **p != request.spec && **p != request.reference)
.cloned()
.collect();
let snapshot = Arc::new(HtmlSnapshot::freeze(SnapshotSelection {
root: request.root.clone(),
entry: request.artifact.clone(),
served,
bound: vec![request.spec.clone(), request.reference.clone()],
})?);
let spec: Value =
serde_json::from_slice(snapshot.bytes(&request.spec).ok_or("missing bound spec")?)
.map_err(|e| e.to_string())?;
if spec["comp"] != request.reference {
return Err("state and spec disagree on the approved reference".into());
}
let ids: Vec<_> = spec["regions"]
.as_array()
.ok_or("missing spec regions")?
.iter()
.filter(|r| r["medium"] == "raster")
.map(|r| r["id"].as_str().ok_or("raster region missing id"))
.collect::<Result<_, _>>()?;
let width = spec["compSize"]["width"]
.as_f64()
.ok_or("missing reference width")?;
let height = spec["compSize"]["height"]
.as_f64()
.ok_or("missing reference height")?;
if width <= 0. || height <= 0. {
return Err("invalid reference dimensions".into());
}
let frames: Vec<(&str, Option<[u32; 2]>)> = match request.stage {
EntryStage::Hero => vec![("hero", None)],
EntryStage::Responsive => vec![
(
"desktop",
Some([1440, (height * 1440. / width).ceil() as u32]),
),
(
"mobile",
Some([390, 844.max((height * 390. / width).ceil() as u32)]),
),
],
};
if ids.is_empty() {
return capture_text_only(request, snapshot, &inventory, &frames, forbidden, clock);
}
let comp = snapshot.bytes(&request.reference).ok_or("reference is not bound to snapshot")?;
let mut forbidden: Vec<&[u8]> = forbidden.to_vec();
forbidden.push(comp);
// Each raster region's plate path and its box in comp pixels.
let mut plates = Vec::new();
let mut boxes = Vec::new();
for region in spec["regions"].as_array().into_iter().flatten().filter(|r| r["medium"] == "raster") {
let id = region["id"].as_str().unwrap_or("raster");
let plate = region["plate"].as_str().ok_or_else(|| format!("raster region {id} has no plate"))?;
if plate == request.reference || plate == request.spec {
return Err(format!("raster region {id} names the approved comp ({plate}) as its plate. A plate is the region's own artwork, never the comp."));
}
if let Some(reason) = snapshot.bytes(plate).and_then(|bytes| forbidden_content(plate, bytes, &forbidden)) {
return Err(format!("raster region {id}'s plate {plate} {reason}. A plate is the region's own artwork, never the comp."));
}
plates.push(plate.to_string());
boxes.push(region["px"].clone());
}
let mut evidence = EntryEvidence {
report: json!({"schema":"native-entry-capture-v1","inputSnapshot":snapshot.digest(),"manifest":snapshot.manifest(),"artifact":request.artifact,"stage":match request.stage {EntryStage::Hero=>"hero",EntryStage::Responsive=>"responsive"},"scope":"Fresh static HTML rendering and scoped raster evidence. No independent aesthetic approval.",
"integrityScope":"the comp and approved screenshots are never served to the page; images outside the declared raster regions cover under 15% of each frame",
"servedToPage":snapshot.manifest()["files"].as_array().into_iter().flatten().filter(|f| f["served"] == true).map(|f| json!({"path":f["path"],"sha256":f["sha256"]})).collect::<Vec<_>>(),
"frameProofs":{},"clock":clock.json()}),
frames: vec![],
};
for (name, viewport) in frames {
// Mobile is captured as actual page evidence; the desktop comp does
// not prescribe mobile artwork positions. Do not score its placements.
let selected = if name == "mobile" {
&ids[..1]
} else {
&ids[..]
};
// Images outside the declared raster regions contradict the spec as
// they would on a page that declares none; that is what catches a
// re-encoded comp the byte checks cannot see. Hero and desktop keep
// the comp's layout, so the region boxes (scaled to the frame width)
// are excluded. Mobile reflows away from them, so there the declared
// plates are excluded wherever they land.
let exclude = if name == "mobile" {
json!({"paths": plates})
} else {
let scale = viewport.map(|v| v[0] as f64 / width).unwrap_or(1.);
let scaled: Vec<Value> = boxes
.iter()
.map(|b| {
let v = |k: &str| b[k].as_f64().unwrap_or(0.) * scale;
json!({"x":v("x"),"y":v("y"),"w":v("w"),"h":v("h")})
})
.collect();
json!({"boxes": scaled})
};
snapshot.take_requested()?;
let captured = snapshot.capture_regions_at_viewport(
&mut CdpAssetRenderer::from_process_env().pinned_at(clock.epoch_ms).measuring_raster_coverage(exclude),
&request.spec,
selected,
true,
viewport,
);
// Judge what the page asked for before anything else, so a capture
// that failed because the comp was withheld says why.
check_requests(name, &snapshot, request, &forbidden)?;
let mut regions = captured?;
if regions.iter().any(|r| {
r.receipt["stableCapture"] != true || r.receipt["batchStabilityVerified"] != true
}) {
let details = regions
.iter()
.filter(|r| {
r.receipt["stableCapture"] != true
|| r.receipt["batchStabilityVerified"] != true
})
.take(4)
.map(|r| {
format!(
"{}: {}",
r.receipt["regionId"].as_str().unwrap_or("region"),
r.receipt["individualCaptureReason"]
.as_str()
.or_else(|| r.receipt["reason"].as_str())
.unwrap_or("capture identity changed")
)
})
.collect::<Vec<_>>()
.join("; ");
return Err(format!(
"{name} native capture did not retain a stable bound document: {details}"
));
}
let coverage = regions
.first()
.map(|r| r.receipt["rasterCoverage"].clone())
.ok_or("raster coverage was not measured")?;
if !coverage["share"].is_number() {
return Err(format!("{name} raster coverage was not measured: {}", coverage["unavailable"].as_str().unwrap_or("no measurement")));
}
for region in &mut regions {
if let Some(receipt) = region.receipt.as_object_mut() {
receipt.remove("rasterCoverage");
}
}
let share = coverage["share"].as_f64().unwrap_or(1.);
if share >= TEXT_ONLY_RASTER_SHARE_MAX {
return Err(format!("{name} raster capture refused: images outside the declared raster regions cover {}% of the viewport (limit {}%): {}. The spec declares every raster in the first viewport as a raster region: declare this image as one (comp-spec --regions), or remove it and draw that area in code.", (share * 100.).round(), (TEXT_ONLY_RASTER_SHARE_MAX * 100.) as u32, largest_images(&coverage)));
}
evidence.report["frameProofs"][name] = json!({"rasterCoverage": coverage});
let png = regions[0]
.images
.iter()
.find(|i| i.name == "baseline.png")
.ok_or("native capture has no baseline image")?
.png
.clone();
evidence.frames.push(FrameEvidence {
name: name.into(),
png,
regions,
});
}
snapshot.verify_current()?;
Ok(Box::new(FrozenEntry {
snapshot,
manifest: None,
evidence,
}))
}
}
/// A first viewport with no raster region has no asset to intervene on, so the
/// asset adapter has nothing to measure. Capture each frame the way the
/// assembled-page review captures the page it shows the user (same snapshot
/// transport, pinned local scripts, verified dependencies, font check and
/// double-screenshot stability), so an approved review screenshot and the gate's
/// frame come from one capture method. Frames carry no region receipts: there is
/// no rendered-presence check to run without artwork.
///
/// The page is served what the review serves: the entry plus the dependencies the
/// hero review manifest declares for it, or, before any review names this entry,
/// the static inventory. Either way the bound spec and comp are never served, and
/// a page that loads or embeds the comp (or an approved screenshot) is refused,
/// so the comparison cannot be satisfied by showing the reference itself.
fn capture_text_only(
request: &EntryRequest,
raster: Arc<HtmlSnapshot>,
inventory: &[String],
frames: &[(&str, Option<[u32; 2]>)],
forbidden: &[&[u8]],
clock: CaptureClock,
) -> Result<Box<dyn CapturedEntry>, String> {
let spec: Value = serde_json::from_slice(raster.bytes(&request.spec).ok_or("missing bound spec")?)
.map_err(|e| e.to_string())?;
let size = |k: &str| {
spec["compSize"][k]
.as_u64()
.and_then(|v| u32::try_from(v).ok())
.filter(|v| *v > 0)
.ok_or_else(|| format!("missing reference {k}"))
};
let (width, height) = (size("width")?, size("height")?);
let comp = raster.bytes(&request.reference).ok_or("reference is not bound to snapshot")?;
let mut forbidden: Vec<&[u8]> = forbidden.to_vec();
forbidden.push(comp);
let (declared, manifest) = declared_dependencies(&request.root, &request.artifact)?;
let policy = if declared.is_some() { "hero-review-manifest" } else { "static-inventory" };
let names: Vec<String> = match &declared {
Some(deps) => {
let mut names = vec![request.artifact.clone()];
for dep in deps {
if !inventory.contains(dep) {
return Err(format!("hero review dependency {dep} is not a static browser file in the project (hidden, package or source-only paths are never served)"));
}
names.push(dep.clone());
}
names
}
None => inventory.to_vec(),
};
// Reuse the bytes the first snapshot froze; nothing is read from disk twice.
let mut files = BTreeMap::new();
for name in names {
if name == request.spec || name == request.reference {
continue;
}
let bytes = raster.bytes(&name).ok_or_else(|| format!("{name} is not in the frozen inputs"))?;
// Served files are checked when the page loads them (below), under either
// policy: a file that never reaches the page cannot show the reference.
files.insert(name, bytes.to_vec());
}
let page = Arc::new(PageSnapshot::from_pinned(request.artifact.clone(), files)?);
let env = impeccable_common::process_env();
let exe = discovery::find_browser(&env).map_err(|e| format!("browser unavailable: {e:?}"))?;
let mut browser = Browser::launch(&exe, &[], false).map_err(|e| e.message)?;
let result = (|| -> Result<EntryEvidence, String> {
let browser_version = browser.version().map_err(|e| e.message)?;
let mut evidence = EntryEvidence {
report: json!({"schema":"native-entry-capture-v1","inputSnapshot":raster.digest(),"manifest":raster.manifest(),"artifact":request.artifact,"stage":match request.stage {EntryStage::Hero=>"hero",EntryStage::Responsive=>"responsive"},"scope":"Fresh static HTML rendering of a first viewport with no raster region. No independent aesthetic approval.","captureMethod":"assembled-page-viewport","integrityScope":"assembled-page viewport from frozen inputs; the comp and approved screenshots are never served; images cover under 15% of each frame; no raster presence check (no raster region)","dependencyPolicy":policy,"servedToPage":page.manifest()["files"],"browser":browser_version,"frameProofs":{},"clock":clock.json()}),
frames: vec![],
};
for &(name, viewport) in frames {
let [w, h] = viewport.unwrap_or([width, height]);
let (png, proof) = render_page(
&mut browser,
page.clone(),
w,
h,
&json!({"x":0,"y":0,"w":1,"h":1}),
None,
true,
true,
true,
clock.epoch_ms,
)
.map_err(|e| {
// Both the network check and the image-decode check name the path
// the page asked for; the comp is never served, so either fires.
let asked = format!("/{}", request.reference);
if e.split(|c: char| c.is_whitespace() || c == ',').any(|t| t.trim_end_matches('.') == asked) {
format!("{name} text-only capture refused: the page loads the approved comp ({}). Draw the first viewport in code.", request.reference)
} else {
format!("{name} text-only capture failed: {e}")
}
})?;
for path in proof["observedDependencies"].as_object().into_iter().flatten().map(|(p, _)| p) {
let bytes = page.bytes(path).ok_or("observed dependency is not in the page snapshot")?;
if let Some(reason) = forbidden_content(path, bytes, &forbidden) {
return Err(format!("{name} text-only capture refused: the page loads {path}, which {reason}. Draw the first viewport in code."));
}
}
// Byte checks cannot see a re-encoded copy. The spec says every raster
// in this viewport is a raster region and it declares none, so a large
// image contradicts the spec whatever its bytes are.
let coverage = &proof["rasterCoverage"];
let share = coverage["share"].as_f64().ok_or("raster coverage was not measured")?;
if share >= TEXT_ONLY_RASTER_SHARE_MAX {
return Err(format!("{name} text-only capture refused: images cover {}% of the viewport (limit {}%): {}. The spec declares no raster region, so a large image contradicts it: declare the image as a raster region in the spec (comp-spec --regions), or remove it and draw that area in code.", (share * 100.).round(), (TEXT_ONLY_RASTER_SHARE_MAX * 100.) as u32, largest_images(coverage)));
}
evidence.report["frameProofs"][name] = proof;
evidence.frames.push(FrameEvidence {
name: name.into(),
png,
regions: vec![],
});
}
Ok(evidence)
})();
browser.close();
let mut evidence = result?;
if let Some((_, bytes)) = &manifest {
evidence.report["reviewManifestSha256"] = json!(capture_sha256(bytes));
}
let entry = FrozenEntry { snapshot: raster, manifest, evidence };
entry.verify_current()?;
Ok(Box::new(entry))
}
/// The dependency list the hero review manifest declares for this entry, when it
/// names one: the same closure the assembled-page review pins and serves.
fn declared_dependencies(
root: &Path,
artifact: &str,
) -> Result<(Option<Vec<String>>, Option<(PathBuf, Vec<u8>)>), String> {
let path = root.join(".impeccable").join("review").join("hero.json");
let Ok(bytes) = fs::read(&path) else {
return Ok((None, None));
};
let Ok(manifest) = serde_json::from_slice::<Value>(&bytes) else {
return Ok((None, None));
};
let pages: Vec<&Value> = manifest["components"]
.as_array()
.into_iter()
.flatten()
.filter(|c| c["preview"]["kind"] == "page" && c["preview"]["path"] == artifact)
.collect();
if manifest["stage"] != "hero" || pages.len() != 1 {
return Ok((None, None));
}
let deps = pages[0]["dependencies"]
.as_array()
.ok_or("hero review manifest: the page component has no dependencies list")?
.iter()
.map(|d| d.as_str().map(|s| s.replace('\\', "/")).ok_or("hero review manifest: dependencies must be paths"))
.collect::<Result<Vec<_>, _>>()?;
Ok((Some(deps), Some((path, bytes))))
}
/// The largest images a coverage measurement names, for a refusal.
fn largest_images(coverage: &Value) -> String {
coverage["largest"]
.as_array()
.into_iter()
.flatten()
.take(3)
.map(|i| format!("{} ({}% of the viewport)", i["what"].as_str().unwrap_or("image"), (i["share"].as_f64().unwrap_or(0.) * 100.).round()))
.collect::<Vec<_>>()
.join(", ")
}
/// Refuse a raster frame whose page asked for a bound input it is never served
/// (the spec or the comp), or loaded a file that is, or inlines, a forbidden
/// image. Only files the page requested are judged, so an unused backup of the
/// comp elsewhere in the project does not block an honest page.
fn check_requests(
name: &str,
snapshot: &HtmlSnapshot,
request: &EntryRequest,
forbidden: &[&[u8]],
) -> Result<(), String> {
for path in snapshot.take_requested().map_err(|e| format!("{name} raster capture refused: {e}"))? {
if path == request.reference || path == request.spec {
return Err(format!("{name} raster capture refused: the page loads the approved comp ({path}). Show the declared plates and draw the rest of the first viewport in code."));
}
if !snapshot.is_served(&path) {
continue;
}
let bytes = snapshot.bytes(&path).ok_or("requested file is not in the frozen inputs")?;
if let Some(reason) = forbidden_content(&path, bytes, forbidden) {
return Err(format!("{name} raster capture refused: the page loads {path}, which {reason}. Show the declared plates and draw the rest of the first viewport in code."));
}
}
Ok(())
}
/// Whether a served file is, or inlines as base64, one of the forbidden images.
fn forbidden_content(name: &str, bytes: &[u8], forbidden: &[&[u8]]) -> Option<&'static str> {
use base64::Engine;
let text = matches!(
Path::new(name).extension().and_then(|x| x.to_str()).map(str::to_ascii_lowercase).as_deref(),
Some("html" | "htm" | "css" | "js" | "mjs" | "svg")
)
.then(|| String::from_utf8_lossy(bytes));
// Line breaks and spaces inside a data URI do not change the image it decodes to.
let text = text.map(|t| t.chars().filter(|c| !c.is_whitespace()).collect::<String>());
for image in forbidden {
if bytes == *image {
return Some("is a copy of the approved reference");
}
// A data URI of the image carries its base64 from the first byte, so a
// leading run of it identifies the embed.
if let Some(text) = &text {
let encoded = base64::engine::general_purpose::STANDARD.encode(image);
let probe = &encoded[..encoded.len().min(512)];
if probe.len() >= 64 && text.contains(probe) {
return Some("embeds the approved reference as a data URI");
}
}
}
None
}
/// Enumerate only static browser files. Never serve hidden state, source-only
/// extensions or package trees. A bound/required file omitted here is an error.
pub fn static_inventory(root: &Path) -> Result<Vec<String>, String> {
fn walk(
root: &Path,
dir: &Path,
depth: usize,
visited: &mut usize,
out: &mut Vec<String>,
) -> Result<(), String> {
if depth > 12 {
return Err("static input inventory exceeds directory-depth budget".into());
}
let mut entries = fs::read_dir(dir)
.map_err(|e| e.to_string())?
.collect::<Result<Vec<_>, _>>()
.map_err(|e| e.to_string())?;
entries.sort_by_key(|e| e.file_name());
for entry in entries {
*visited += 1;
if *visited > 8192 {
return Err("static input inventory exceeds entry budget".into());
}
let name = entry.file_name().to_string_lossy().to_string();
if name.starts_with('.') || name == "node_modules" {
continue;
}
let kind = entry.file_type().map_err(|e| e.to_string())?;
if kind.is_symlink() {
return Err(format!(
"symlink in static input tree: {}",
entry.path().display()
));
}
if kind.is_dir() {
walk(root, &entry.path(), depth + 1, visited, out)?;
} else if kind.is_file()
&& matches!(
entry.path().extension().and_then(|x| x.to_str()),
Some(
"html"
| "htm"
| "css"
| "js"
| "mjs"
| "png"
| "jpg"
| "jpeg"
| "webp"
| "gif"
| "svg"
| "avif"
| "ico"
| "woff"
| "woff2"
| "ttf"
| "otf"
)
)
{
out.push(
entry
.path()
.strip_prefix(root)
.map_err(|e| e.to_string())?
.to_str()
.ok_or("non-UTF8 static path")?
.replace('\\', "/"),
);
if out.len() > 1024 {
return Err("static input inventory exceeds file budget".into());
}
}
}
Ok(())
}
let root = fs::canonicalize(root).map_err(|e| e.to_string())?;
let mut out = Vec::new();
walk(&root, &root, 0, &mut 0, &mut out)?;
Ok(out)
}