Merge pull request #36 from pgsty/codex/review-followups

fix: close post-1.0 review defects

Author: Vonng

.github/workflows/ci.yml

@@ -310,10 +310,12 @@ jobs:
         run: python3 -m unittest discover -s tests/migrations -t .
 
       - name: Check output structure and security
-        run: python3 bin/check-output.py
+        run: |
+          python3 tests/test_checker_inputs.py
+          python3 bin/check-output.py --public tests/site/public
 
       - name: Check the naming namespace
-        run: python3 bin/check-namespace.py
+        run: python3 bin/check-namespace.py --public tests/site/public
 
       - name: Check the parameter contract and legacy-key errors
         run: python3 bin/check-params.py

AGENTS.md

@@ -29,13 +29,13 @@ accepted decisions, dated research, and active proposals.
 - Put accepted rationale under `content/docs/design/decisions/` in the site
   repository and dated, non-normative evidence under `research/`. Preserve
   retired drafts in Git history and `CHANGELOG.md`, not a local planning tree.
-- Run the smallest owning checker here first. Then validate the real site from
-  `../oink.pgsty.com` with the sibling theme replacement:
+- Run the smallest owning checker here first. Then validate the real site
+  through its sibling-checkout Make targets:
 
 ```sh
-HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /Users/vonng/pgsty/oink' npm test
-HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /Users/vonng/pgsty/oink' npm run test:browser
-HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /Users/vonng/pgsty/oink' hugo server -DFE
+make -C ../oink.pgsty.com check
+make -C ../oink.pgsty.com browser
+make -C ../oink.pgsty.com dev
 ```
 
 - Use the documentation site for rendered EN/ZH, desktop/mobile, light/dark,

CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to OINK are documented here. The project follows
 [Semantic Versioning](https://semver.org/) for published tags.
 
+## [Unreleased]
+
+### Fixed
+
+- `params.ui.scroll_spy` and the page-level `scroll_spy` override no longer
+  emit an unused patch runtime. OINK's normal shell runtime already tracks the
+  active outline heading. Both keys remain accepted as quiet compatibility
+  no-ops throughout 1.x and may be removed only in a future breaking release.
+- Plain page Print and overlapping Book Print aggregates no longer race on the
+  page's `tdBookAggregate` Store flag. One per-page cached coordinator now
+  renders and exposes the distinct plain and Book variants in a fixed order.
+
 ## [1.0.0] - 2026-08-29
 
 OINK 1.0.0 declares the current component, configuration, content, output, and

CLAUDE.md

@@ -49,21 +49,26 @@ responsive, and visual validation against the sibling documentation site.
 ```sh
 python3 bin/check-shell.py               # shell, blog, page-end contracts
 python3 bin/check-components.py          # component and render-hook contracts
-python3 bin/check-output.py              # rendered structure/runtime/security
+python3 bin/check-output.py              # fresh strict fixture + output checks
+python3 bin/check-namespace.py           # fresh strict fixture + namespace checks
 python3 bin/check-goldens.py             # HTML/print/Markdown/RSS/LLMS goldens
 python3 bin/check-params.py              # config shapes and warning fallbacks
 python3 bin/check-i18n.py                 # locale schema parity
 node --test 'tests/js/**/*.test.js'       # browser-runtime units
 hugo --source tests/site --printPathWarnings --panicOnWarning
 ```
 
-From `../oink.pgsty.com`, validate and preview the real bilingual site with the
-current theme checkout:
+Both rendered-output checkers build into a temporary directory when invoked as
+shown. Pass `--public tests/site/public` only to reuse an intentionally fresh
+fixture that was built separately; this mode does not rebuild that fixture.
+
+Validate and preview the real bilingual site with the current sibling theme
+checkout:
 
 ```sh
-HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /Users/vonng/pgsty/oink' npm test
-HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /Users/vonng/pgsty/oink' npm run test:browser
-HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /Users/vonng/pgsty/oink' hugo server -DFE
+make -C ../oink.pgsty.com check
+make -C ../oink.pgsty.com browser
+make -C ../oink.pgsty.com dev
 ```
 
 Migration is dry-run unless `--write` is explicit:

assets/js/docs-shell.js

@@ -443,7 +443,7 @@
   /*
    * Below xl the TOC rail is hidden, which used to take the table of contents
    * and the taxonomy clouds with it. Rather than render a second copy —
-   * duplicate ids would break the scrollspy and the disclosure wiring — the
+   * duplicate ids would break the outline tracker and the disclosure wiring — the
    * single block is moved into a slot in the sidebar drawer and moved back on
    * the way up.
    *

assets/js/keyboard-nav.js

@@ -582,8 +582,7 @@
           return true;
         }
       }
-      var fallback = doc.querySelector('[data-td-theme-toggle]') ||
-        doc.querySelector('[data-td-theme-toggle]');
+      var fallback = doc.querySelector('[data-td-theme-toggle]');
       if (!fallback || typeof fallback.click !== 'function') return false;
       fallback.click();
       return true;

assets/js/scrollspy-patch.js

@@ -1,4 +1,4 @@
-// Hydrate the active path of a cached sidebar without fetching page fragments.
+// Hydrate the active path of a visible cached sidebar without fetching fragments.
 (function () {
   'use strict';
 
@@ -13,7 +13,7 @@
 
   function init() {
     var menu = document.getElementById('td-sidebar-menu');
-    if (!menu || !menu.classList.contains('d-none')) return;
+    if (!menu || !menu.hasAttribute('data-td-sidebar-hydrate-active')) return;
 
     var canonical = document.querySelector('link[rel="canonical"]');
     var current = pathOf(canonical ? canonical.href : window.location.href);
@@ -46,6 +46,7 @@
       item = item.parentElement && item.parentElement.closest('li')
     ) {
       item.classList.add('td-active-path');
+      item.classList.remove('td-shell-tree__item--hidden');
       var toggle = item.querySelector(
         ':scope > .td-shell-tree__row [data-td-shell-tree-toggle]',
       );
@@ -61,7 +62,10 @@
       }
     }
 
-    menu.classList.remove('d-none');
+    // Resolve the marker-scoped transition suppression before restoring the
+    // ordinary disclosure motion used after hydration.
+    menu.getBoundingClientRect();
+    menu.removeAttribute('data-td-sidebar-hydrate-active');
   }
 
   if (document.readyState === 'loading') {

assets/js/sidebar-nav.js

@@ -413,6 +413,16 @@
     visibility 0s;
 }
 
+// A cached tree discovers its active branch after the first paint. Apply that
+// initial state without fading readable text through a sub-AA opacity; once
+// hydration removes the marker, reader-triggered disclosure transitions keep
+// their normal motion.
+[data-td-sidebar-hydrate-active] .td-shell-tree__children,
+[data-td-sidebar-hydrate-active] .td-shell-tree__row,
+[data-td-sidebar-hydrate-active] .td-shell-tree__link {
+  transition: none;
+}
+
 .td-shell-tree__children-inner {
   overflow: hidden;
   min-height: 0;

assets/scss/td/shell/_sidebar.scss

@@ -16,7 +16,7 @@
 from pathlib import Path
 from typing import Any
 
-from test_site import TEST_SITE, fixture_config
+from test_site import TEST_SITE, fixture_config, run_hugo_process
 
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -201,7 +201,7 @@ def validate_external_mount_actions() -> None:
 
     with tempfile.TemporaryDirectory(prefix="oink-external-actions-") as temp:
         public = Path(temp) / "public"
-        result = subprocess.run(
+        result = run_hugo_process(
             [
                 "hugo",
                 "--source",
@@ -382,7 +382,15 @@ def validate_manifest(
         require(commands["print_now"]["title"] == "立即打印", "out-of-order ZH merge failed")
 
 
-def run_invalid_build(helper: Any, workspace: Path, name: str, command_yaml: str, expected: str) -> None:
+def run_invalid_build(
+    helper: Any,
+    workspace: Path,
+    name: str,
+    command_yaml: str,
+    expected: str,
+    *,
+    strict_canary: bool,
+) -> None:
     site = workspace / f"invalid-{name}"
     output = workspace / f"invalid-public-{name}"
     shutil.copytree(helper.SITE_FIXTURE_PATH, site)
@@ -396,7 +404,7 @@ def run_invalid_build(helper: Any, workspace: Path, name: str, command_yaml: str
     )
     config = config.replace("    weight: 1\n  zh:\n", "    weight: 1\n" + addition + "  zh:\n")
     (site / "hugo.yaml").write_text(config, encoding="utf-8")
-    result = subprocess.run(
+    result = run_hugo_process(
         [
             "hugo",
             "--source",
@@ -422,6 +430,10 @@ def run_invalid_build(helper: Any, workspace: Path, name: str, command_yaml: str
     require(expected in result.stdout, f"invalid {name} build missed {expected!r}:\n{result.stdout}")
     require(result.returncode == 0,
             f"invalid {name} command stopped the build instead of warning:\n{result.stdout}")
+    require(
+        (output / "en/docs/guides/tutorial/index.html").is_file(),
+        f"invalid {name} command emitted no safe page output",
+    )
     if "unsafe URL" in expected:
         # The dropped URL must not reach any rendered page -- that is the
         # whole point of refusing it.
@@ -431,22 +443,23 @@ def run_invalid_build(helper: Any, workspace: Path, name: str, command_yaml: str
             if path.is_file() and "javascript:alert" in path.read_text(errors="ignore")
         ]
         require(not leaked, f"invalid {name} command leaked its unsafe URL into {leaked[:3]}")
-    strict = subprocess.run(
-        [
-            "hugo", "--source", str(site), "--themesDir", str(ROOT.parent),
-            "--destination", str(output) + "-strict",
-            "--cacheDir", str(workspace / "cache-invalid-strict"),
-            "--panicOnWarning",
-        ],
-        cwd=site,
-        env={**os.environ, "HUGO_ENVIRONMENT": "development"},
-        text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, check=False,
-    )
-    require(strict.returncode != 0, f"invalid {name} command survived --panicOnWarning")
+    if strict_canary:
+        strict = run_hugo_process(
+            [
+                "hugo", "--source", str(site), "--themesDir", str(ROOT.parent),
+                "--destination", str(output) + "-strict",
+                "--cacheDir", str(workspace / "cache-invalid-strict"),
+                "--panicOnWarning",
+            ],
+            cwd=site,
+            env={**os.environ, "HUGO_ENVIRONMENT": "development"},
+            text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, check=False,
+        )
+        require(strict.returncode != 0, f"invalid {name} command survived --panicOnWarning")
 
 
 def strict_fails(site: Path, workspace: Path, name: str) -> bool:
-    strict = subprocess.run(
+    strict = run_hugo_process(
         ["hugo", "--source", str(site), "--themesDir", str(ROOT.parent),
          "--destination", str(workspace / f"strict-{name}"),
          "--cacheDir", str(workspace / f"cache-strict-{name}"), "--panicOnWarning"],
@@ -818,8 +831,25 @@ def main() -> int:
                     'field "keywords" must be an array of strings',
                 ),
             }
+            strict_canaries = {
+                "unknown",          # built-in action lookup
+                "both",             # action/URL exclusivity
+                "callback",         # unsupported fields
+                "javascript",       # URL policy
+                "duplicate",        # command identity
+                "reserved",         # built-in identity
+                "numeric-title",    # scalar field types
+                "scalar-keywords",  # list field types
+            }
             for name, (yaml, expected) in invalid_cases.items():
-                run_invalid_build(helper, workspace, name, yaml, expected)
+                run_invalid_build(
+                    helper,
+                    workspace,
+                    name,
+                    yaml,
+                    expected,
+                    strict_canary=name in strict_canaries,
+                )
 
             validate_custom_url_policy(helper, workspace)