README.md

README.md is a file in Bane's Lab Site. 109 lines of code and 0 definitions.

<!-- Auto-generated 2026-09-29T00:21Z v8 -->

# @banes-lab/web

<!-- concern:overview -->

## Purpose

This member is the banes-lab.com site. Each page is registered by a record under `presentation/records/`, whose `registerPage` call names the page and loads its view from `presentation/views/` only when the page is opened, so the bundle carries one chunk per page. The route coordinator listens for `route.requested` events, renders the page into the main region and emits `route.changed`, and the panel and the mobile menu mark the active page from that event.

The copy lives in `configuration/strings/` as typed `Section` data (`types/document.types.ts`). `presentation/renderers/block.renderer.ts` renders its blocks (`types/block.types.ts`, `types/grammar.types.ts`). Each kind of page goes through its own renderer:

- the legal pages and the FAQ through `document.renderer.ts`
- the PAG, methodology, architecture, ontology and anatomy pages through `tab.widget.ts`
- the methodology and architecture chapters through `chapter.renderer.ts`, which sets the prose beside cited panels (`panel.renderer.ts`), with pan and zoom from `panel.component.ts` and diagrams fetched by digest in `diagram.renderer.ts`

The ontology and anatomy pages render snapshots that the build writes. The ontology page renders `core/generated/ontology.generated.ts` through the converters in `domain/converters/`. The anatomy page renders `core/generated/anatomy.generated.ts`, which holds one snapshot per tree that `core/registries/anatomy.tree.registry.ts` declares: this site, the content build, the Coordination Surface package, the tool configs and the governance host. For each file it shows the walk, the definitions, the document checks and the source (`anatomy.renderer.ts`, `folder.renderer.ts`, `walk.renderer.ts`, `source.renderer.ts`).

The build's `links` step passes every content module through `linkTabs` in `domain/converters/link.vocabulary.converter.ts`, which turns the first mention of an ontology term or another page's chapter in each section into a link, and writes each page's linked tabs to its own module in `core/generated/`, such as `core/generated/methodology.page.generated.ts`. `reference.widget.ts` shows the record or chapter behind such a link on hover, focus or tap, together with the places in the anatomy that implement it, which the build resolves into the relation graph.

Icons live in `configuration/icons/`, section ids in `core/ids/` and resource locations in `core/assets/`. Every element is built through `core/factories/element.factory.ts`. Inline markup in the copy is converted to text runs by `core/converters/markup.converter.ts` and rendered by `presentation/renderers/text.renderer.ts`, so parsed HTML never reaches the page. `page.renderer.ts` derives each route's head: the title, description, canonical address, Open Graph type, and the JSON-LD graph from `schema.renderer.ts`. In that graph, the page and each section name their JSON payload, their Markdown version and the page's catalog index as encodings. `text.converter.ts` turns a rendered page into the Markdown alternate that the copy button and the prerender share.
<!-- /concern:overview -->

<!-- concern:use -->

## When to use

- To add a page, you add a `<subject>.record.ts` under `presentation/records/` whose `registerPage` call names the page and loads its `<subject>.view.ts` from `presentation/views/`. The glob barrel discovers the record, the prerender writes its route, payload and alternate, and the browser fetches the view's chunk only when the page is opened.
- To change copy, you edit the `<subject>.strings.ts` module that owns it, because no view carries a literal. A section that outgrows the file-length limit continues in `<subject>.fragment.strings.ts`, and a chapter section cites each of its panels by tag from the prose.
- To cite the ontology or another page, you write the record's exact name or the chapter's exact title, and the vocabulary linker resolves it. An anchor that the vocabulary does not carry goes through `stageLink`, `layerLink` or `nodeLink` from `link.converter.ts`.
- To add a block kind, you extend `types/block.types.ts` (or `grammar.types.ts`), render it in `block.renderer.ts`, style it in `presentation/styles/`, and declare it in the panel kinds if a chapter may cite it.
- To change the page shell, you edit the panel widget, the menu widget and their styles under `presentation/`.
- To add a tree to the anatomy page, you add its declaration to `core/registries/anatomy.tree.registry.ts` with its export name, path key, tab and repository, its tab id to `core/ids/anatomy.ids.ts`, and its label to `folder.strings.ts`.
- To add a relation to the site graph, you add one record to `RELATIONS` in `configuration/constants/graph.constants.ts`, which derives its pair, whether tooltips carry it, whether its reverse rolls up to the folder, and the catalog leaf fields its reverse is checked on.

## When NOT to use

- Deploying the site belongs to the deploy member, which owns the server, nginx and the upload. This member only builds.
- The ontology, anatomy and diagram snapshots are written by the vite plugins in the build member, `@banes-lab/build-scripts`, so they are not edited by hand here.
- The query catalog under `/json/api`, its schemas and the journal of moved addresses are built by the build member, and the `/q` endpoint is an nginx script under `banes-lab.root/banes-lab.server/runtime/entrypoints/`.
- Governance code, meaning the rules and validators, belongs to `.govlab/` and the `govlab.*` members.
- The tests for this member live under `codebase.testing/test.web/`.

<!-- /concern:use -->

<!-- concern:charts -->

## Architecture charts

The structure, logical-flow and dependency diagrams derived from the source AST live in [_code.info.generated/mermaid-charts.generated.md](./_code.info.generated/mermaid-charts.generated.md).
<!-- /concern:charts -->

<!-- concern:install -->

## Install

The `workspaces` glob in the root `package.json` resolves this member, and every third-party dependency is hoisted from the root. `npm run dev` from the root serves the site over HTTPS with a generated self-signed certificate. `npm run build -w @banes-lab/web` runs the build plugins in `vite.config.ts`, writes the static site into the output declared as `builds.web` in `project.paths/paths.yaml`, and then renders the methodology repository and its wiki.

## Quick start

```ts EXAMPLE: Register a page
import { registerPage } from "#domain/registries/page.registry";

registerPage({
    description: HOME_DESCRIPTION,
    icon: HOME_ICON,
    id: HOME_PAGE,
    listed: true,
    load: async () => (await import("#presentation/views/home.view")).PAGE,
    order: 10,
    title: HOME_TITLE,
});
```

```ts EXAMPLE: Request a route from anywhere
import { emitEvent } from "#core/buses/base.bus";
import { ROUTE_REQUESTED } from "#core/ids/route.ids";

emitEvent({ name: ROUTE_REQUESTED, page: HOME_PAGE });
```

```ts EXAMPLE: Link a content module against the ontology and the chapter vocabulary
import type { LinkedPage } from "#types/vocabulary.types";
import { METHODOLOGY_CONTENT } from "#configuration/strings/methodology.strings";
import { METHODOLOGY_PAGE } from "#core/ids/page.ids";

export const LINKED_PAGES: readonly LinkedPage[] = [
    { name: "METHODOLOGY_TABS", page: METHODOLOGY_PAGE, tabs: METHODOLOGY_CONTENT },
];
```

<!-- /concern:install -->

<!-- concern:api -->

## API

The package exposes no public API.
<!-- /concern:api -->

<!-- concern:config -->

## Configuration

- `vite.config.ts` — The application build and its plugins in the order they run, with the roots, the output and the development certificate resolved through `@ssot/paths`. The anatomy snapshot is derived before the build starts.
- `.govlab/shared/configs/taxonomy.config.ts `containers`` — Declares this member as a governed root with the containers `configuration`, `core`, `domain`, `presentation` and `runtime`, and the flat `types` folder.
- `configuration/constants/vocabulary.constants.ts` — The ambiguous phrases that the vocabulary linker never turns into links.
- `configuration/constants/evidence.source.constants.ts` — The registry that ties ontology records and chapters to the constructs in this member that implement them. The build resolves it into the relation graph, and the reference widget reads both directions from the graph chunks.

<!-- /concern:config -->

<!-- concern:deps -->

## Dependencies

- `@govlab/constants`

<!-- /concern:deps -->

<!-- concern:ai-context -->

## AI context

- Views carry no copy. A new string is a constant in the `<subject>.strings.ts` module that owns it.
- Interactive controls (buttons, inputs) are constructed only inside `presentation/components/*.component.ts`.
- A child component emits events and its parent subscribes to them. A widget never receives a callback to call upward.
- A `*.generated.ts` asset is written by a build plugin and is not edited by hand. When one is missing or out of date, the build has not run.
- Tests for this member live in `codebase.testing/test.web/`, each at its subject's mirrored folder path, and import it by package specifier.

<!-- /concern:ai-context -->

<!-- concern:domains -->

## Domains

This package serves these software domains, which `_manifest.json` declares in `domains` from the two-tier software-domain vocabulary (`meta → sub`):

- **content** — copywriting-strings
- **frontend-ui** — dom-construction, navigation

<!-- /concern:domains -->

<!-- concern:quality-governance -->

## Quality governance

The canonical quality catalog resolves the quality concepts that govern this package. `_manifest.json` declares them in `governedBy`, and a lint package derives them from the concepts its own rules enforce. Each maps to the custom lint rules that enforce it:

- **separation-of-concerns** — _complexity_
- **type-safety** — _correctness_

<!-- /concern:quality-governance -->

<!-- concern:disposal -->

## Disposal

- Remove the member's workspace entry from the root `package.json`, and the `#host/*` imports key.
- Remove its governed-root entry from `containers` and `specialContainers` in `.govlab/shared/configs/taxonomy.config.ts`.
- Remove the `app` branch from `project.paths/paths.yaml`.
- Delete the directory, reinstall, and run `npm run verify`.

<!-- /concern:disposal -->

<!-- concern:metrics -->

---

experimental · 0 exports · 1 deps · 0 principles · 2 concepts
<!-- /concern:metrics -->