content-explorer/workplans/evidence/CONTENT-WP-0002-ImplementationNotes.md

CONTENT-WP-0002 implementation notes

Date: 2026-10-13

T01 — tokens, layout, header, hero, table

Pinned upstream: b594d7433bf4e408b44215e25e5304696d6f840e.

R4 applies. ResultsTable.tsx in the pin depends on translation, column filters, column resize, and infinite scroll. SiteChrome.tsx and src/app/layout.tsx depend on the OnCo mark, garden art, command palette, and medical footer. Those files were not copied whole.

What landed under ui/:

• Color tokens, type classes (.display, .kicker), card, chip, button, hero wash, skip link, and sticky table rules, adapted from src/app/globals.css. The table class is records.
• A sticky header and a footer. The header links to / and #records only, so it does not point at kind routes that do not exist yet.
• A hero with the upstream structure and Content Explorer copy. The sample is examples/dataspaces/systems-thinking/snapshot.json.
• ResultsTable renders columns, an empty state, sort buttons, and aria-sort. The parent owns the sort. URL query state stays with T04.

Deviations:

• Accent values stay the upstream pink (#c2185b / #d6336c). That color is part of the token file being adapted. It is not used as a medical claim.
• Geist font files are not fetched. The sans stack is the system UI font.
• Garden keyframes, the OnCo mark, column resize, column filters, and paging are omitted.
• Sort state is local React state.

Provenance: ui/NOTICE contains Copyright (c) 2026 OnCo and the MIT permission text. Adapted files name the pin.

Checks on 2026-10-13:

• npm test in ui/: 4 tests passed (sort order, empty state, sort button, aria-sort).
• npm run typecheck in ui/: tsc --noEmit passed.
• python3 scripts/check_ui_boundary.py: no oncology, cancer, drug, or target token on UI import lines, and the notice is present. This does not close T07; that gate still has to cover the later components.
• python3 scripts/validate_fixtures.py and python3 -m unittest tests.test_contract tests.test_ingest passed.
• next dev on 127.0.0.1:3400 returned the home page (HTTP 200, Next.js 16.3.4). The HTML contained the Content Explorer heading, the skip link, #main, and the fixture titles Feedback, Requisite variety, and Stock and flow model. The rendered page did not contain the words oncology or cancer. The dev server was stopped after that check. No browser pane was available, so this was an HTTP render check, not a keyboard or screenshot pass. Those remain T09.

Not done after T01: kind index, detail, BrowserRow, URL facets, keyboard states, both dataspaces, the formal import gate, or keyboard and small-screen smoke.

T02 — registry kind index and entity detail

The kind list is the kinds array on each snapshot. Routes are /{dataspace}/{kind}/ and /{dataspace}/{kind}/{slug}/. The slug is the part of the entity id after the kind. Both example dataspaces are loaded from examples/dataspaces/. An unknown kind or slug returns 404.

EntityDetail.tsx from the pin was not copied. The detail page is a greenfield view: title, TL;DR, summary, tags, sources, claims, and neighbouring relations with the manifest's forward and inverse labels. Search, facets, and URL sort state stay with later tasks. The neighbour list is not the CONTENT-WP-0004 graph journey.

The header kind links are the active dataspace's registry. On / that dataspace is systems-thinking.

Checks on 2026-10-13, after T02:

• npm test in ui/: 8 tests passed, including registry membership for both dataspaces, the Feedback neighbour, and static markup for the kind heading and the system-boundary claim.
• npm run typecheck in ui/ passed.
• python3 scripts/check_ui_boundary.py, fixture validation, and tests.test_contract / tests.test_ingest passed.
• next dev on 127.0.0.1:3400 returned HTTP 200 for /, /systems-thinking/concept/, /systems-thinking/concept/feedback/, /systems-thinking/concept/system-boundary/, /software-architecture/pattern/, and /software-architecture/concept/coupling/. Unknown kind and slug returned 404. The rendered pages did not contain the words oncology or cancer. The server was stopped. No browser pane was available, so this was an HTTP render check.

Not done after T02: BrowserRow mapper, URL facets and sort, keyboard search and empty/error states, the T06 both-dataspace gate for search and filter, the formal import gate, provenance gate, or keyboard and small-screen smoke.

T03 — generic browser row and cell renderers

mapBrowserRow is a pure function. It copies the OnCo row fields id, name, tldr, route, facets, cols, and sortKeys. It does not copy molecule, target, schematic, cancer-icon, or section-icon fields. Known cells are a name link, summary text, tag chips, and a kind link. A facet key other than tags is an empty list. A column key with no cell renders nothing.

Kind pages show the columns named in that kind's kindViews entry (name, tldr, tags in both fixtures). The dataspace home shows name, kind, and summary because that table mixes kinds. renderCell uses a renderer registry keyed by column or cell kind, so a caller can replace one cell without a domain widget.

Checks on 2026-10-13, after T03:

• npm test in ui/: 10 tests passed. The new tests cover the Feedback tag facet, an empty unknown facet, a replaced tag renderer, and the name link.
• npm run typecheck, scripts/check_ui_boundary.py, fixture validation, and the contract and ingest tests passed.
• next dev on 127.0.0.1:3400 returned the home table with a Kind column, and the concept and pattern indexes with Tags (regulation, translation). The server was stopped. No browser pane was available.

Not done after T03: URL facets and sort, keyboard search and empty/error states, the T06 gate for search and filter, the formal import gate, the provenance gate, or keyboard and small-screen smoke. Facet values were on the row; they did not filter the table yet.

T04 — shareable query, facets, and sort

The query string follows the pinned table shape: q is the search text, a facet key repeats for each selected value (tags=regulation&tags=structure), and sort is the column key with a leading - when descending. The default sort is omitted. Search is written when the form is submitted. A facet button or a sort button writes immediately. Each write is a history entry.

applyTableView filters, then sorts. Within one facet, any selected value matches. Every selected facet key must match. Search looks at the name, the summary, and facet values.

Checks on 2026-10-13, after T04:

• npm test in ui/: 14 tests passed. The view tests round-trip a query and filter rows. The history test submits a search, selects a tag, reverses the sort, then goes back to the unfiltered table and forward to the sorted tag view.
• The same test dispatches popstate on window after pushState and checks that the history reader reports the new query.
• npm run typecheck, scripts/check_ui_boundary.py, fixture validation, and the contract and ingest tests passed.
• next dev on 127.0.0.1:3400 rendered /systems-thinking/concept/ with the search field and the tag regulation. The server was stopped. No desktop browser was available, so back and forward were exercised in the history test rather than in a graphical browser.

Not done after T04: keyboard search and empty/error/loading states, the T06 gate for both dataspaces across search and filter, the formal import gate, the provenance gate, or keyboard and small-screen smoke. A facet key other than tags still has no values in these fixtures.

T05 — keyboard search, empty, loading, error, and narrow layout

/ focuses the record search when the key press is not already in a field. Escape clears the draft, and clears a submitted query. An empty catalog says "No records." A search or facet that matches nothing says "No records match this view." and offers Clear view. status="loading" and status="error" replace the table with a status or an alert. Route changes use app/loading.tsx and app/error.tsx.

The search form stacks in one column and the header wraps instead of staying on one fixed row. The table still scrolls sideways when the columns are wider than the screen.

Checks on 2026-10-13, after T05:

• npm test in ui/: 17 tests passed. The new tests cover loading, error, both empty messages, Clear view, / focus, and Escape.
• npm run typecheck, scripts/check_ui_boundary.py, fixture validation, and the contract and ingest tests passed.
• next dev on 127.0.0.1:3400 rendered /systems-thinking/concept/ with the search hint and the narrow-layout classes. The server was stopped. No graphical browser was available, so a narrow viewport was not walked. That smoke stays with T09.

Not done after T05: the T06 gate that browse, search, filter, sort, and detail pass together for both dataspaces, the formal import gate, the provenance gate, or the keyboard and small-screen smoke. A facet key other than tags still has no values in these fixtures.

T06 — both dataspaces

No new screen. The gate runs the same browse, search, filter, sort, and detail path on systems-thinking and software-architecture.

For each field the check loads the concept index, confirms every row route stays inside that field, searches for one record by its name, filters by one of its tags, sorts names descending, and renders that record's detail with its summary and sources. The home of each field also links to the other.

Checks on 2026-10-13, after T06:

• npm test in ui/: 18 tests passed, including components/both-dataspaces.test.tsx.
• npm run typecheck, scripts/check_ui_boundary.py, fixture validation, and the contract and ingest tests passed.
• next dev on 127.0.0.1:3400 returned HTTP 200 for /systems-thinking/, /software-architecture/, /systems-thinking/concept/feedback/, and /software-architecture/concept/coupling/. Each page contained the other field's name or the record's sources. The server was stopped. Search and sort on those pages were exercised in the UI test, because the filter runs in the browser after the HTML is sent.

Not done after T06: the formal import gate, the provenance gate, or the keyboard and small-screen smoke. A facet key other than tags still has no values in these fixtures.

T07 — domain import gate

scripts/check_ui_boundary.py reads every import, require, dynamic import(), and CSS @import under ui/. It fails when the statement names oncology, cancer, drug, or target, including a name such as CancerIcon. A property such as event.target is not an import and stays allowed. The kind labels and navigation labels in both example fixtures are checked the same way.

tests/test_ui_boundary.py rejects sample imports for each forbidden token and accepts the shipped UI.

Checks on 2026-10-13, after T07:

• python3 -m unittest tests.test_ui_boundary tests.test_contract tests.test_ingest passed (15 tests).
• python3 scripts/check_ui_boundary.py and python3 scripts/validate_fixtures.py passed.

Not done: the provenance gate, or the keyboard and small-screen smoke. A facet key other than tags still has no values in these fixtures.

T08 — provenance headers and notices

A file under ui/ that says it was adapted or reduced from OnCo must name the pin in research/baseline/ONCO_PIN, Copyright (c) 2026 OnCo, MIT License, and ui/NOTICE. ui/NOTICE keeps the MIT permission text and that same pin. The footer keeps the MIT license and the pin in the page text. A file that says OnCo was not copied is not treated as an adapted copy.

SkipLink, SiteHeader, Hero, and PageHeader already named OnCo and the license. They did not name the pin. Those four headers now include b594d7433bf4e408b44215e25e5304696d6f840e. ResultsTable, globals.css, browser-row, and table-view already had the full header.

Checks on 2026-10-13, after T08:

• python3 -m unittest tests.test_ui_provenance tests.test_ui_boundary tests.test_contract tests.test_ingest passed (21 tests).
• python3 scripts/check_ui_provenance.py, python3 scripts/check_ui_boundary.py, and python3 scripts/validate_fixtures.py passed.

Not done: the keyboard and small-screen smoke. A facet key other than tags still has no values in these fixtures.

T09 — keyboard and small-screen smoke

The smoke is workplans/evidence/CONTENT-WP-0002-T09-smoke.json. It opens the production home page in Chromium at 1280×800 and 390×844. Tab focuses the skip link. Enter lands on /#main. The search field receives "Feedback" and Enter. The URL becomes /?q=Feedback and the Feedback link is the matching record. Escape clears the query and returns the URL to /.

The browser job protocol accepts Tab, Enter, and Escape. It rejects /, so the slash shortcut stays covered by ui/components/RecordBrowser.states.test.tsx.

next dev did not hydrate when the browser service closed its websocket, because the dev client waits on the HMR socket. The smoke therefore used npx next build and npx next start --hostname 0.0.0.0 --port 3400 from ui/. allowedDevOrigins includes host.docker.internal so a container can load the dev server. The passing run did not use the dev server.

The browser was a separate container of image sha256:8d6fd5a8172cf906bb503642ed620761945c5138b86f6396c36f65cbe6def441 on 127.0.0.1:18084, with only http://host.docker.internal:3400 allowed. The fixture container on port 18083 was left running.

Passed run 99f366b8-2af2-46a6-bedf-a6342e2cb923 at 2026-10-13T21:47:49Z. Playwright 1.64.0, Chromium 156.0.8078.4. All 34 steps passed. At 390px the header wraps onto a second line, the search form stacks, and the kind links scroll sideways. Screenshot hashes:

• desktop-3-baseline.png 1e995d262ca6217e04bf6c17d0e1f089102db3ef3f6a4028aec34074191c0522
• desktop-16-keyboard.png 825187674d958ad08295dff3a28da893a5d2acd86e7e3c19ba9e58f1dc4f128e
• narrow-3-baseline.png 01844c2596ec22815f50a26331778326d4c1b5a4e6846a31c44295e5147fbbd5
• narrow-16-keyboard.png 88986ac815ecda0e75536e04ce85a0ec10eefa7c5ca73274d999fa2c4fe62562

The PNGs stayed in /tmp/content-explorer-t09-smoke-05. The dev server and the smoke container were stopped after the run.

A facet key other than tags still has no values in these fixtures.