Skip to content

OINK 1.1 release review, 2026-09-20

Five reproduced runtime defects, documentation corrections, validation evidence, and the OINK 1.1 publication follow-up.
Historical release review (2026-09-20)

This record captures the pre-release validation and five runtime fixes for OINK 1.1, followed by the v1.1.0 publication record.

Scope and baseline

The review starts at theme commit 75052f8a3106d13ef313644836a5ad545135f484, after the community fixes and image-copy repair. It examines the v1.0.0..main changes and behavior requested by issues #40, #41, #42, #44, and merged PR #43. It also examines bilingual documentation and the release boundary. The previous review records those original reports and their implementation.

The method inspects owning JavaScript, templates and contracts, then exercises transition boundaries with focused regressions that compare failing assertions before each fix with the repaired implementation. Theme checkers and the real sibling documentation site’s integration and browser suites provide the subsequent acceptance evidence.

At this snapshot, the public release, documentation go.mod pin and configured public version are still v1.0.0. The blog consumer’s theme pin is unchanged.

Findings and repairs

Five P2 correctness defects were reproduced and repaired in theme commit 08f6563, pushed to main. They concern ordering in the new APIs and existing focus/navigation behavior. They require no new configuration format or content migration.

Finding Trigger and observed failure Minimal repair
P2: sidebar readiness fires before hydration A consumer awaits OinkSidebar.ready or handles oink:sidebar-ready. The readiness microtask can run between DOMContentLoaded listeners. The cached sidebar’s active path is not yet hydrated, so consumers see incomplete initial state. After all initialization listeners and aside placement finish, resolve readiness in the next task. Preserve the existing ready Promise and event contract.
P2: a pending action can enter a native choice menu Start an asynchronous search-tail action, then activate a native choice such as theme selection. The pending guard ran after the choice branch. This allowed that menu to replace the pending action’s rows. Check pending activation before any row-type branch. After completion, ordinary choice activation is available again.
P2: a collapsed right TOC rail remains focusable Collapse the desktop right rail. Its hidden control and links remain keyboard targets. Focus can stay inside the hidden panel. Apply inert and aria-hidden to the rail panel. Move focus to the visible restore control. On restoration, return focus to the column control. When relocated, keep the movable aside outside that isolation.
P2: arrow navigation skips non-link groups From a child of a divider-only group, Left/a cannot consistently return to the parent disclosure and fold it. The group button is absent from the tree’s focus sequence. Include group disclosure buttons in tree focus navigation and direct-parent traversal. Right/d opens or enters the group. Previous/next page navigation still uses links only.
P2: drawer focus wrapping counts inert descendants In the mobile drawer, collapse an aside group and wrap with Shift+Tab. Hidden descendants still count as focusable. They can make the wrap fail or leave focus stuck. Exclude controls under inert or hidden from the drawer’s focusable set. Also exclude controls with hidden/collapsed visibility.

Implementation and regression ownership:

Finding Theme implementation Owning regression
Readiness assets/js/sidebar-state.js tests/js/sidebar-state.test.js; site tests/browser/community-feedback.spec.mjs snapshots the active path from both readiness signals in EN/ZH
Pending choice assets/js/command-palette.js tests/js/command-palette.test.js exercises pending extension → native choice → completion → available choice
Right rail assets/js/docs-shell.js Site tests/browser/community-feedback.spec.mjs covers EN/ZH collapse, Tab traversal, restoration, reload and aside relocation across desktop/tablet/mobile
Group keys assets/js/keyboard-nav.js tests/js/keyboard-nav.test.js covers LTR/RTL, arrows/WASD and link-only paging. Site community tests exercise real EN/ZH groups.
Drawer trap assets/js/docs-shell.js Site community tests collapse relocated groups and wrap Shift+Tab and Tab. They assert that focus never enters an inert or hidden subtree.

The readiness and pending-choice regressions failed against the previous implementation before their fixes. The right-rail browser assertions also failed in both English and Chinese before isolation was added. The repairs remain small: they change timing, move one pending guard earlier, add explicit rail isolation, and adjust tree focus targets and the drawer’s visibility filter.

These changes preserve the already accepted behavior: both root collectors honor sidebar_root_menu: false, and non-link groups retain their children. Pointer focus avoids incidental article outlines while keyboard cues remain visible. Search-tail callbacks retain their cancellation and handoff contract. The image preview fix continues to use an accessible name without inserting helper text into copied article content. Final regression results are recorded below.

Documentation readiness

The current documentation update covers 28 files in 14 EN/ZH pairs:

  • The six Design contract pairs use candidate-v1.1.0. They describe implemented main behavior without announcing a published release.
  • Navigation, layout and front-matter guides match current root filtering, divider groups and bilingual deployment paths. They also match the centered navbar, narrow-screen drawer and in-place navbar reveal behavior.
  • Organization and palette guides explain runtime load order, readiness and feature detection. They also explain site-owned persistence/integrations. Keyboard and image guides explain the fixes and the older-version boundary.
  • Installation guidance distinguishes the validation toolchain from the public version. Existing heading IDs remain stable. The new sidebar API heading has a matching Chinese ID.

The two 1.1.0 release-note files and two upgrade-guide files are also prepared. The release note remains a draft/candidate. Both home-page release entries point to the published 1.0 version.

Validation snapshot

Counts below describe the 2026-09-20 snapshot for theme 08f6563. Site acceptance uses the sibling checkout through a command-scoped module replacement. Local site checks used Hugo Extended 0.166.0, Node 26.9.0 and Playwright 1.62.1. Candidate CI used the pinned Hugo 0.165.0 toolchain. The 0.160.1 floor was checked separately with the official binary.

Check Result and scope
Baseline 75052f8 CI Passed all three jobs: pinned Hugo toolchain, browser runtime tests and Book publication. Exact baseline run.
JavaScript unit suite after the fixes Passed: 44 tests.
Official Hugo Extended 0.160.1 Passed the focused i18n and shell checkers. i18n covers 32 catalogs × 194 messages. The real documentation site also passed a production build against the local candidate with --panicOnWarning: 376 pages per language. The draft release is absent, and both home-page links point to 1.0.0.
Bilingual source and style checks Passed including this report: 129/129 page pairs, 988 source headings, Markdown style and git diff --check.
Final focused theme checkers Passed: shell, palette, keyboard and image zoom.
Final real-site non-browser suite make check passed all 57 tests. It checked 200 rendered content pages, 331 linked HTML pages, 39,803 internal links and 3,863 fragment links. Only the two expected Markdown goldens changed, for the release summary and documentation index. The floor production build also passed link checks: 327 pages, 39,059 internal links and 3,833 fragments.
Final browser suite make browser passed all 149 Chromium tests in eight suites. The suites contain 30 accessibility, 45 responsive/blog/palette, 16 keyboard, 14 content components and 18 code blocks. They also contain 4 scenarios, 5 theme-color and 17 community regressions. Coverage includes the full multilingual sitemap and six viewport widths. It also includes light/dark, forced colors, clipboard and no-script cases.
Agent documentation sample 93/100 (A) across 50 same-origin sampled pages. Sampled links resolve. 49 pages provide Markdown, and all 270 sampled code fences close correctly. The checker warns that the HTML llms.txt discovery hint is missing or too deep.
Rendered review Reviewed the Chinese release note in a desktop dark view and English in a narrow light view. Right-rail collapse removes its descendants from the accessibility tree. It also moves focus to the restore button. Restoration returns focus to the visible rail button.
Final theme revision and its CI 08f6563 passed all three jobs: Hugo 0.165.0, browser runtime tests and Book publication. Exact candidate run.
Public v1.1.0 tag, consumer upgrade and deployment Not performed.

Within this review’s scope, no unresolved implementation blocker remains. The candidate is ready for the publication steps below.

Repeat the checks from sibling checkouts. During development, keep the published dependency pin intact:

# From the theme repository
node --test tests/js/*.test.js
python3 bin/check-shell.py
python3 bin/check-palette.py
python3 bin/check-keyboard.py
python3 bin/check-image-zoom.py

# The site Make targets apply a command-scoped sibling module replacement.
make -C ../oink.pgsty.com check
make -C ../oink.pgsty.com browser

Remaining publication steps

Publication has not been executed. After the final revision passes acceptance:

  1. Finalize CHANGELOG.md, the release date and the release record. Publish the v1.1.0 tag and GitHub Release from the verified theme revision.
  2. Verify that the module proxy resolves that tag to the intended revision.
  3. Update the documentation consumer pin and version configuration together with its home-page release entry and contract status. Set the release-note state to draft: false in the same update.
  4. Rebuild and accept the documentation site using the published dependency, without HUGO_MODULE_REPLACEMENTS. Deploy it and verify the public routes.

A future improvement is an earlier, consistent llms.txt discovery hint for agents entering through HTML.

Limits

Browser verification ran in Chromium. The automated accessibility gate covers theme-owned surfaces while retaining its existing exclusions for vendored Redoc and Swagger UI, and Hugo 0.160.1 floor checks ran on the focused i18n, shell, and production build paths.

Publication follow-up

After this review, the v1.1.0 release was published on 2026-09-20 from 3a18234. Only the changelog differs from the accepted 08f6563 implementation. All three release-commit CI jobs passed before the annotated tag and stable GitHub Release were published.

A download with a fresh cache, using only the official Go module proxy, resolved the tag to that exact commit. Its .info, .mod, .zip, version-list entry and signed checksum record were verified. The module checksum is h1:121L5g57ChRCPyidzEBBcln2Co+0zYRQ+XDDXjymd0Q=. The go.mod checksum is h1:pHvbUhJCfseB41n5RGwsF7abT3i32VSTpofLQoq4b7Y=. The public records are the proxy version and checksum entry.

The documentation publication update pins v1.1.0 in go.mod and go.sum. It aligns the advertised version and both home-page release entries, and publishes both release notes. It also promotes the six contract pairs to released-v1.1.0. The historical acceptance tables above continue to describe the earlier sibling-checkout run. The site’s Site checks and Browser quality workflows track published-dependency validation separately, with both Go and Hugo module workspaces disabled.

Local validation of this published module passed all 57 non-browser tests and 26 focused Palette/community browser tests. It also passed the strict production build with 378 pages per language. The checks ran with GOWORK=off, HUGO_MODULE_WORKSPACE=off, and no HUGO_MODULE_REPLACEMENTS. The publication commit’s Browser quality workflow also runs the complete 149-test browser suite.

Last modified 2026-11-06 · docs: publish OINK v1.5.1 release notes (18cca3d)