claude-dev-env 8.65.1 → 8.66.0

package/hooks/blocking/artifact_dark_mode_gate.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that stops an artifact page from publishing when dark mode hides its text.
+
+The artifact service wraps every published page in a skeleton whose style pins
+``body`` to a light background and dark text. A page that flips its theme
+tokens on ``html`` alone keeps that light body in dark mode, and its light
+dark-mode text lands on it. A plain local render has no wrapper, so the page
+looks fine there and fails once published.
+
+This gate renders the page inside that same wrapper in headless Chromium,
+once under ``prefers-color-scheme: dark`` and once with ``data-theme="dark"``
+on the root element::
+
+    Artifact {"action": "publish", "file_path": "page.html"}  -> rendered
+        body stays light, or visible text under 4.5:1      -> denied
+        every check holds                                  -> allowed
+    Artifact {"action": "read", ...}                       -> allowed
+    Artifact {"asset": true, ...} or {"type_url": ...}     -> allowed
+    a publish whose file_path is not .html                 -> allowed
+
+A host without Playwright or Chromium is denied with the install command,
+because an unrendered page is the case this gate exists to stop.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.artifact_dark_mode_gate_constants import (
+    ALL_SKIPPED_PUBLISH_INPUT_KEYS,
+    ALLOW_EXIT_CODE,
+    ARTIFACT_ACTION_INPUT_KEY,
+    ARTIFACT_FILE_PATH_INPUT_KEY,
+    ARTIFACT_PUBLISH_ACTION,
+    ARTIFACT_TOOL_NAME,
+    BLOCK_EXIT_CODE,
+    DARK_MODE_FAILURE_HEADER,
+    GATE_EVENT_NAME,
+    HTML_FILE_SUFFIX,
+    PUBLISH_SKELETON_PREFIX,
+    RENDERER_MISSING_EXIT_CODE,
+    RENDERER_MISSING_HEADER,
+    RENDERER_SCRIPT_PATH,
+    RENDERER_TIMEOUT_SECONDS,
+    RETRY_INSTRUCTION,
+)
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.spawn_readiness_hook_constants import TOOL_INPUT_KEY, TOOL_NAME_KEY
+
+
+def published_page_path(tool_name: object, tool_input: object) -> Path | None:
+    """Return the local HTML page a call publishes as an artifact page, or None.
+
+    >>> published_page_path("Artifact", {"file_path": "/tmp/page.html"})
+    PosixPath('/tmp/page.html')
+    >>> published_page_path("Artifact", {"action": "read", "url": "x"}) is None
+    True
+
+    Args:
+        tool_name: The tool the session called.
+        tool_input: The tool input.
+
+    Returns:
+        The page path for a page publish, or None for any other call.
+    """
+    if tool_name != ARTIFACT_TOOL_NAME or not isinstance(tool_input, dict):
+        return None
+    if (
+        tool_input.get(ARTIFACT_ACTION_INPUT_KEY, ARTIFACT_PUBLISH_ACTION)
+        != ARTIFACT_PUBLISH_ACTION
+    ):
+        return None
+    if any(tool_input.get(each_key) for each_key in ALL_SKIPPED_PUBLISH_INPUT_KEYS):
+        return None
+    file_path = tool_input.get(ARTIFACT_FILE_PATH_INPUT_KEY)
+    if not isinstance(file_path, str) or not file_path.lower().endswith(HTML_FILE_SUFFIX):
+        return None
+    return Path(file_path)
+
+
+def wrap_in_publish_skeleton(page_source: str) -> str:
+    """Return the page as the artifact service serves it, inside its skeleton.
+
+    Args:
+        page_source: The HTML the session is about to publish.
+
+    Returns:
+        The skeleton head and body opening followed by the page source.
+    """
+    return PUBLISH_SKELETON_PREFIX + page_source
+
+
+def _run_renderer(wrapped_page_path: Path) -> subprocess.CompletedProcess[str] | str:
+    try:
+        return subprocess.run(
+            ["node", str(RENDERER_SCRIPT_PATH), str(wrapped_page_path)],
+            capture_output=True,
+            text=True,
+            timeout=RENDERER_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except FileNotFoundError:
+        return "node is not installed; install Node.js, then run: npm install -g playwright && npx playwright install chromium"
+    except subprocess.TimeoutExpired:
+        return f"the render took longer than {RENDERER_TIMEOUT_SECONDS} seconds"
+
+
+def render_findings(page_source: str) -> tuple[dict[str, list[str]] | None, str]:
+    """Render the wrapped page in both dark signals and return what failed.
+
+    Args:
+        page_source: The HTML the session is about to publish.
+
+    Returns:
+        The findings by dark signal (empty when the page passes) and an empty
+        message, or None and the reason the renderer could not run.
+    """
+    with tempfile.TemporaryDirectory() as scratch_directory:
+        wrapped_page_path = Path(scratch_directory) / "wrapped_page.html"
+        wrapped_page_path.write_text(wrap_in_publish_skeleton(page_source), encoding="utf-8")
+        completed_render = _run_renderer(wrapped_page_path)
+    if isinstance(completed_render, str):
+        return None, completed_render
+    if completed_render.returncode == RENDERER_MISSING_EXIT_CODE:
+        return None, completed_render.stderr.strip()
+    try:
+        findings_by_signal = json.loads(completed_render.stdout)
+    except json.JSONDecodeError:
+        return None, completed_render.stderr.strip() or "the renderer printed no result"
+    return findings_by_signal, ""
+
+
+def format_block_reason(findings_by_signal: dict[str, list[str]]) -> str:
+    """Return the deny message that lists each failed check under its dark signal.
+
+    Args:
+        findings_by_signal: Findings keyed by the dark signal that produced them.
+
+    Returns:
+        The message the session reads when the publish is denied.
+    """
+    all_lines = [DARK_MODE_FAILURE_HEADER]
+    for each_signal, each_signal_findings in findings_by_signal.items():
+        all_lines.append(f"Under {each_signal}:\n")
+        all_lines.extend(f"- {each_finding}\n" for each_finding in each_signal_findings)
+    return "".join(all_lines) + RETRY_INSTRUCTION
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    page_path = published_page_path(hook_input.get(TOOL_NAME_KEY), hook_input.get(TOOL_INPUT_KEY))
+    if page_path is None or not page_path.is_file():
+        return ALLOW_EXIT_CODE
+    findings_by_signal, renderer_problem = render_findings(page_path.read_text(encoding="utf-8"))
+    if findings_by_signal is None:
+        block_reason = RENDERER_MISSING_HEADER + renderer_problem
+    elif findings_by_signal:
+        block_reason = format_block_reason(findings_by_signal)
+    else:
+        return ALLOW_EXIT_CODE
+    log_hook_block(
+        Path(__file__).name,
+        GATE_EVENT_NAME,
+        block_reason,
+        tool_name=ARTIFACT_TOOL_NAME,
+        offending_input_preview=str(page_path),
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/artifact_dark_mode_render.cjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+"use strict";
+
+const childProcess = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const MINIMUM_CONTRAST_RATIO = 4.5;
+const MAXIMUM_DARK_PAGE_LUMINANCE = 0.2;
+const MAXIMUM_REPORTED_TEXT_FAILURES = 8;
+const TEXT_SNIPPET_LENGTH = 60;
+const PAGE_LOAD_TIMEOUT_MILLISECONDS = 15000;
+const RENDERER_MISSING_EXIT_CODE = 3;
+const ALL_DARK_SIGNALS = [
+  { name: "prefers-color-scheme: dark", colorScheme: "dark", dataTheme: null },
+  { name: 'data-theme="dark"', colorScheme: "light", dataTheme: "dark" },
+];
+
+function loadPlaywright() {
+  try {
+    return require("playwright");
+  } catch (localError) {
+    const globalRoot = childProcess.execSync("npm root -g", { encoding: "utf8" }).trim();
+    return require(path.join(globalRoot, "playwright"));
+  }
+}
+
+function measurePage([maximumDarkPageLuminance, minimumContrastRatio, snippetLength]) {
+  const parseColor = (colorText) => {
+    const channels = (colorText.match(/[\d.]+/g) || []).map(Number);
+    return { red: channels[0] || 0, green: channels[1] || 0, blue: channels[2] || 0, alpha: channels.length > 3 ? channels[3] : 1 };
+  };
+  const channelLuminance = (channel) => {
+    const scaled = channel / 255;
+    return scaled <= 0.03928 ? scaled / 12.92 : Math.pow((scaled + 0.055) / 1.055, 2.4);
+  };
+  const luminance = (color) => 0.2126 * channelLuminance(color.red) + 0.7152 * channelLuminance(color.green) + 0.0722 * channelLuminance(color.blue);
+  const contrastRatio = (first, second) => {
+    const lighter = Math.max(luminance(first), luminance(second));
+    const darker = Math.min(luminance(first), luminance(second));
+    return (lighter + 0.05) / (darker + 0.05);
+  };
+  const canvasColor = { red: 255, green: 255, blue: 255, alpha: 1 };
+  const effectiveBackground = (element) => {
+    for (let current = element; current; current = current.parentElement) {
+      const background = parseColor(getComputedStyle(current).backgroundColor);
+      if (background.alpha > 0.5) {
+        return background;
+      }
+    }
+    return canvasColor;
+  };
+  const isVisible = (element) => {
+    const style = getComputedStyle(element);
+    const box = element.getBoundingClientRect();
+    return style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity) > 0 && box.width > 0 && box.height > 0;
+  };
+  const allFindings = [];
+  const pageBackground = effectiveBackground(document.body);
+  if (luminance(pageBackground) > maximumDarkPageLuminance) {
+    allFindings.push(`the page background stays light (${getComputedStyle(document.body).backgroundColor} on body); give body an explicit background from the theme tokens`);
+  }
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  const seenElements = new Set();
+  for (let textNode = walker.nextNode(); textNode; textNode = walker.nextNode()) {
+    const element = textNode.parentElement;
+    const text = textNode.textContent.trim();
+    if (!text || !element || seenElements.has(element) || ["SCRIPT", "STYLE", "TEMPLATE", "NOSCRIPT"].includes(element.tagName)) {
+      continue;
+    }
+    seenElements.add(element);
+    if (!isVisible(element)) {
+      continue;
+    }
+    const foreground = parseColor(getComputedStyle(element).color);
+    const background = effectiveBackground(element);
+    const ratio = contrastRatio(foreground, background);
+    if (ratio < minimumContrastRatio) {
+      allFindings.push(`text "${text.slice(0, snippetLength)}" has contrast ${ratio.toFixed(2)}:1 (${getComputedStyle(element).color} on rgb(${background.red}, ${background.green}, ${background.blue}))`);
+    }
+  }
+  return allFindings;
+}
+
+async function checkSignal(browser, pageHtml, darkSignal) {
+  const page = await browser.newPage({ colorScheme: darkSignal.colorScheme });
+  page.setDefaultTimeout(PAGE_LOAD_TIMEOUT_MILLISECONDS);
+  try {
+    await page.setContent(pageHtml, { waitUntil: "load", timeout: PAGE_LOAD_TIMEOUT_MILLISECONDS }).catch(() => undefined);
+    if (darkSignal.dataTheme) {
+      await page.evaluate((themeName) => document.documentElement.setAttribute("data-theme", themeName), darkSignal.dataTheme);
+    }
+    const allFindings = await page.evaluate(measurePage, [MAXIMUM_DARK_PAGE_LUMINANCE, MINIMUM_CONTRAST_RATIO, TEXT_SNIPPET_LENGTH]);
+    return allFindings;
+  } finally {
+    await page.close();
+  }
+}
+
+async function main() {
+  const pagePath = process.argv[2];
+  const pageHtml = fs.readFileSync(pagePath, "utf8");
+  let playwright;
+  try {
+    playwright = loadPlaywright();
+  } catch (loadError) {
+    process.stderr.write("Playwright is not installed; run: npm install -g playwright && npx playwright install chromium\n");
+    return RENDERER_MISSING_EXIT_CODE;
+  }
+  let browser;
+  try {
+    browser = await playwright.chromium.launch();
+  } catch (launchError) {
+    process.stderr.write(`Chromium did not start for Playwright; run: npx playwright install chromium (${launchError.message.split("\n")[0]})\n`);
+    return RENDERER_MISSING_EXIT_CODE;
+  }
+  const report = {};
+  try {
+    for (const darkSignal of ALL_DARK_SIGNALS) {
+      const allFindings = await checkSignal(browser, pageHtml, darkSignal);
+      if (allFindings.length > 0) {
+        report[darkSignal.name] = allFindings.slice(0, MAXIMUM_REPORTED_TEXT_FAILURES + 1);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  process.stdout.write(JSON.stringify(report));
+  return 0;
+}
+
+main().then((exitCode) => process.exit(exitCode));

package/hooks/blocking/test_artifact_dark_mode_gate.py

@@ -0,0 +1,114 @@
+"""Behavior tests for the artifact dark mode publish gate."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from blocking.artifact_dark_mode_gate import (
+    render_findings,
+    format_block_reason,
+    published_page_path,
+    wrap_in_publish_skeleton,
+)
+from hooks_constants.artifact_dark_mode_gate_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    PUBLISH_SKELETON_PREFIX,
+)
+
+GATE_SCRIPT_PATH = Path(__file__).resolve().parent / "artifact_dark_mode_gate.py"
+THEME_COLOR_STYLES = (
+    "<style>:root{--paper:#faf9f5;--ink:#141413;color-scheme:light dark}"
+    "@media (prefers-color-scheme: dark){:root:not([data-theme=light]){--paper:#262624;--ink:#faf9f5}}"
+    ":root[data-theme=dark]{--paper:#262624;--ink:#faf9f5}"
+    "html{background:var(--paper);color:var(--ink)}h1{color:var(--ink)}</style>"
+)
+PAGE_WITH_TOKENS_ON_HTML_ONLY = THEME_COLOR_STYLES + "<h1>Weekly totals</h1><p>Three runs today.</p>"
+PAGE_WITH_THEMED_BODY = (
+    THEME_COLOR_STYLES + "<style>body{background:var(--paper);color:var(--ink)}</style>"
+    "<h1>Weekly totals</h1><p>Three runs today.</p>"
+)
+
+
+def _renderer_available() -> bool:
+    if shutil.which("node") is None:
+        return False
+    findings_by_signal, _ = render_findings("<p>probe</p>")
+    return findings_by_signal is not None
+
+
+needs_renderer = pytest.mark.skipif(
+    not _renderer_available(), reason="node Playwright with Chromium is not installed"
+)
+
+
+def _run_gate(tool_input: dict[str, object]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(GATE_SCRIPT_PATH)],
+        input=json.dumps({"tool_name": "Artifact", "tool_input": tool_input}),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_should_return_the_page_path_for_an_html_publish() -> None:
+    assert published_page_path("Artifact", {"file_path": "/tmp/page.html"}) == Path(
+        "/tmp/page.html"
+    )
+
+
+def test_should_skip_reads_assets_typed_creates_and_other_tools() -> None:
+    assert published_page_path("Artifact", {"action": "read", "url": "x"}) is None
+    assert published_page_path("Artifact", {"file_path": "/tmp/logo.html", "asset": True}) is None
+    assert published_page_path("Artifact", {"file_path": "/tmp/data.html", "type_url": "x"}) is None
+    assert published_page_path("Artifact", {"file_path": "/tmp/notes.md"}) is None
+    assert published_page_path("Write", {"file_path": "/tmp/page.html"}) is None
+
+
+def test_should_put_the_page_after_the_skeleton_that_pins_body_light() -> None:
+    wrapped_page = wrap_in_publish_skeleton("<p>x</p>")
+    assert wrapped_page == PUBLISH_SKELETON_PREFIX + "<p>x</p>"
+    assert "background:#faf9f5" in wrapped_page
+
+
+def test_should_list_each_finding_under_its_dark_signal() -> None:
+    block_reason = format_block_reason(
+        {"prefers-color-scheme: dark": ['text "A" has contrast 1.00:1']}
+    )
+    assert "Under prefers-color-scheme: dark:" in block_reason
+    assert '- text "A" has contrast 1.00:1' in block_reason
+    assert "body{background:var(--paper);color:var(--ink)}" in block_reason
+
+
+@needs_renderer
+def test_should_fail_a_page_that_themes_html_but_not_body() -> None:
+    findings_by_signal, _ = render_findings(PAGE_WITH_TOKENS_ON_HTML_ONLY)
+    assert set(findings_by_signal) == {"prefers-color-scheme: dark", 'data-theme="dark"'}
+    assert any(
+        "Weekly totals" in each_finding for each_finding in findings_by_signal['data-theme="dark"']
+    )
+
+
+@needs_renderer
+def test_should_pass_a_page_that_themes_body() -> None:
+    assert render_findings(PAGE_WITH_THEMED_BODY) == ({}, "")
+
+
+@needs_renderer
+def test_should_deny_and_then_allow_the_publish_call(tmp_path: Path) -> None:
+    page_path = tmp_path / "report.html"
+    page_path.write_text(PAGE_WITH_TOKENS_ON_HTML_ONLY, encoding="utf-8")
+    denied_run = _run_gate({"action": "publish", "file_path": str(page_path)})
+    assert denied_run.returncode == BLOCK_EXIT_CODE
+    assert "has unreadable text" in denied_run.stderr
+    page_path.write_text(PAGE_WITH_THEMED_BODY, encoding="utf-8")
+    assert _run_gate({"file_path": str(page_path)}).returncode == ALLOW_EXIT_CODE

package/hooks/features/conduct-gates.md

@@ -12,6 +12,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
+- `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
 
 ## When it fires
 
@@ -23,6 +24,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)`, timeout `10` seconds in `hooks.json`.
+- `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 
 ## Proving it
 
@@ -38,6 +40,7 @@ Preconditions:
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
+- **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
 
 ## Gotchas
 
@@ -47,3 +50,4 @@ Preconditions:
 - The edit marker gate scans replacement cards as well as the message text.
 - The handoff close gate reads the `body` and `comment` fields of issue tools only. A `gh issue close --comment` command in Bash and a pull request body that closes the issue with `Closes #N` do not reach it.
 - The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.
+- The dark mode gate denies a page publish when Node, Playwright or Chromium is missing, and its reason names the install command. It checks both dark signals, `prefers-color-scheme: dark` and `data-theme="dark"` on the root element.

package/hooks/hooks.json

@@ -152,6 +152,16 @@
           }
         ]
       },
+      {
+        "matcher": "Artifact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/artifact_dark_mode_gate.py",
+            "timeout": 60
+          }
+        ]
+      },
       {
         "matcher": "Artifact|Skill",
         "hooks": [

package/hooks/hooks_constants/artifact_dark_mode_gate_constants.py

@@ -0,0 +1,57 @@
+"""Names, limits and messages for the artifact_dark_mode_gate PreToolUse hook."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = [
+    "ALLOW_EXIT_CODE",
+    "ALL_SKIPPED_PUBLISH_INPUT_KEYS",
+    "ARTIFACT_ACTION_INPUT_KEY",
+    "ARTIFACT_FILE_PATH_INPUT_KEY",
+    "ARTIFACT_PUBLISH_ACTION",
+    "ARTIFACT_TOOL_NAME",
+    "BLOCK_EXIT_CODE",
+    "DARK_MODE_FAILURE_HEADER",
+    "GATE_EVENT_NAME",
+    "HTML_FILE_SUFFIX",
+    "PUBLISH_SKELETON_PREFIX",
+    "RENDERER_MISSING_EXIT_CODE",
+    "RENDERER_MISSING_HEADER",
+    "RENDERER_SCRIPT_PATH",
+    "RENDERER_TIMEOUT_SECONDS",
+    "RETRY_INSTRUCTION",
+]
+
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+RENDERER_MISSING_EXIT_CODE = 3
+RENDERER_TIMEOUT_SECONDS = 50
+ARTIFACT_TOOL_NAME = "Artifact"
+ARTIFACT_ACTION_INPUT_KEY = "action"
+ARTIFACT_PUBLISH_ACTION = "publish"
+ARTIFACT_FILE_PATH_INPUT_KEY = "file_path"
+ALL_SKIPPED_PUBLISH_INPUT_KEYS = ("asset", "type_url")
+HTML_FILE_SUFFIX = ".html"
+GATE_EVENT_NAME = "PreToolUse"
+RENDERER_SCRIPT_PATH = (
+    Path(__file__).resolve().parent.parent / "blocking" / "artifact_dark_mode_render.cjs"
+)
+PUBLISH_SKELETON_PREFIX = (
+    "<!doctype html><html><head><meta charset=utf8>"
+    '<meta name=viewport content="width=device-width,initial-scale=1">'
+    "<style>:root{color-scheme:light}body{margin:0;padding:0;"
+    "font:14px -apple-system,BlinkMacSystemFont,sans-serif;"
+    "background:#faf9f5;color:#141413}img{max-width:100%}"
+    "[hidden]:not([hidden=until-found i]){display:none!important}</style>"
+    "</head><body>\n"
+)
+DARK_MODE_FAILURE_HEADER = (
+    "Inside the artifact publish wrapper, this page has unreadable text when the viewer uses dark mode.\n"
+)
+RENDERER_MISSING_HEADER = "The page did not render for its contrast check before publish: "
+RETRY_INSTRUCTION = (
+    "\nThe publish wrapper pins body to a light background and dark text. Set body background and"
+    " color from the page's theme tokens, for example body{background:var(--paper);color:var(--ink)},"
+    ' so both flip under prefers-color-scheme: dark and data-theme="dark". Then publish again.'
+)

package/hooks/hooks_constants/test_artifact_dark_mode_gate_constants.py

@@ -0,0 +1,17 @@
+"""Behavioral tests for the artifact page gate's paths and publish wrapper."""
+
+from hooks_constants.artifact_dark_mode_gate_constants import (
+    PUBLISH_SKELETON_PREFIX,
+    RENDERER_SCRIPT_PATH,
+)
+
+
+def test_renderer_path_names_the_packaged_render_script() -> None:
+    assert RENDERER_SCRIPT_PATH.is_file()
+    assert RENDERER_SCRIPT_PATH.suffix == ".cjs"
+
+
+def test_publish_wrapper_pins_body_light_and_opens_the_body() -> None:
+    assert "body{margin:0;padding:0;" in PUBLISH_SKELETON_PREFIX
+    assert "background:#faf9f5;color:#141413" in PUBLISH_SKELETON_PREFIX
+    assert PUBLISH_SKELETON_PREFIX.endswith("<body>\n")

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.65.1",
+    "version": "8.66.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/policy_lint/adapter_configuration.py

@@ -135,6 +135,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/verify_before_acting.py           -> exempt
         hooks/blocking/session_title_format_gate.py      -> exempt
         hooks/blocking/session_title_stop_gate.py        -> exempt
+        hooks/blocking/artifact_dark_mode_gate.py        -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -163,6 +164,9 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     denies a malformed title, and the other asks for a title before a turn
     ends. They decide the shape of a title and no code or safety policy.
 
+    The artifact page gate denies a page publish whose text is unreadable in
+    dark mode. It decides how a page renders and no code or safety policy.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -71,6 +71,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/verify_before_acting.py",
     "blocking/session_title_format_gate.py",
     "blocking/session_title_stop_gate.py",
+    "blocking/artifact_dark_mode_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/tests/test_adapter_configuration.py

@@ -109,6 +109,14 @@ def test_new_session_title_gate_registrations_are_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_artifact_page_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/artifact_dark_mode_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_blocker_in_staged_change_is_rejected(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/new.py"],