Content-types package

What it is

The bridge between the mesh and whatever consumes it. gtmesh types emits a self-contained TypeScript workspace package (default packages/content-types/) that your static-site generator — or any TypeScript consumer — compiles against. It is the content-types package.

Why it matters

The mesh’s contract is its page schemas and its committed graph. Hand-writing types to match them drifts the moment a schema changes. Generating them keeps the consumer honest: the SSG imports the same shapes the engine guarantees, and gtmesh types --check fails CI the instant the committed package and the schemas disagree.

How it works

gtmesh types reads schemas/ and the page types declared in config.page_types, then writes a buildable package containing:

• per-type page interfaces — one TypeScript interface per page type, derived from its schema;
• a PageType union — the closed set of page types, derived from config.page_types;
• the graph-native reader — loadGraph() (the indexed GraphView over graph/{nodes.jsonl,edges.tsv}, with derived roleOf/byRole/entityOf/edgesOf/membersOf accessors — edgesOf(id, type?) is a node’s whole relationship set, both layers, mirroring Page.edges in the engine) and loadManifest() (the projected site.manifest.json link tree). This is the reader — the old row-shaped loadRegistry()/RegistryEntry reader is removed (§6.2); see the crosswalk if your SSG still uses it;
• page-bundle loaders — to load a page’s content/<id>/index.yaml bundle;
• a redirect reader (loadRedirects()) — reads the url/ALIAS_OF graph layer, returns { from, to } to emit 301s. See Redirects;
• an entities/facet reader + mesh-feed helpers — loadEntities / entitiesByFacet, and breadcrumbs / hubMembers / relatedLinks + the pageSummaries card index, so navigation is a call, not a re-implemented lib/;
• named projections — getProjection(name) returns a typed, cached list of schema-shaped cards (label, thumbnail, tags) from a config mapping;
• co-located asset helpers — assetUrl resolves a bare asset filename to a served URL; copyMeshAssets mirrors the files to your public dir;
• config-derived constants (site.ts) — the section list, the per-environment render set, the site base URL, the facet axes, the thumbnail projection, and the asset base, so the SSG reads engine-owned policy instead of re-declaring it.

The package is self-contained, so the consumer depends on it like any workspace package — no reaching into the mesh internals.

Library API

Everything the package exports, grouped by what it reads. For how these compose into a site build, see Build a website.

Pages — load a page’s content bundle

All accept a PageQuery: { status?, graph?, root?, path? }. Pass status: renderableStatuses(env) to list only the pages an environment renders, and graph to reuse an already-loaded GraphView instead of re-reading it.

Feeds — navigation as cards

Traversal over the mesh link tree, returning ready-to-render PageSummary[]. Page identity + status come from the GraphView (pass the loadGraph() handle as the first argument); the up-link/sibling arrays are a site.manifest.json read. Each accepts opts.status (prune to the render set) and opts.thumbnails (fill card images). See Navigation & relationships.

Projections — schema-shaped cards (projections.ts)

Named projections: a page → a shaped list-item whose shape is a schema (card.schema.yaml → the Card type).

getProjection("productCard")({ status: renderableStatuses(env) })  // → Card[]
  .map(c => ({ href: c.slug, label: c.label, img: c.thumbnail, tags: c.tags }));

Summaries — the card index (summary.ts)

The build-once slug → PageSummary projection: a graph-node + bundle-meta join (label, description, optional thumbnail), scanned once and memoised on the GraphView, so labelling related slugs is O(1) instead of re-parsing bundles. Pass the loadGraph() handle as the first argument.

PageSummary = { slug, type, section, entity, title?, navTitle?, description?, label, thumbnail? }. Pass { thumbnails: THUMBNAILS } to populate thumbnail ({ asset, alt?, caption?, ratio? }); asset is the bare co-located filename (resolve content/<slug>/<asset>).

Graph — the graph-native accessor (graph.ts)

loadGraph(opts?) returns an indexed, read-only GraphView over the committed graph (graph/nodes.jsonl + graph/edges.tsv) — parsed and indexed once per build (no per-call re-parse), source-hidden (you never pass arrays around). It’s a generic accessor: it exposes the raw graph — nodes by id/property + the typed edges — and your SSG builds its own domain lists from the edge relationships it knows. The lib re-encodes no config vocabulary (no cluster/facet/topic groupers), so nothing in it can drift from your gtmesh.config.yaml.

Derived accessors (sugar). The mesh’s authority derivations, computed once per view and reused — so you never hand-roll the apex-edge role scan or the pluralised-hub entity trap. Each wraps the same canonical engine derivation, so roles/entities stay in one place.

g.clustersOf(id).industry      →  g.edgesOf(id, "HAS_INDUSTRY").map(e => e.to)   // every value, as node ids
g.topicsOf(id)                 →  g.edgesOf(id, "MEMBER_OF").map(e => e.to)      // the same memberships, as node ids

Edge-type knowledge (HAS_APPLICATION, HAS_COLLECTION, …) is domain-specific and lives in your SSG — which is exactly where it belongs. Each page bundle also carries its stable node id at _brief.id — use it as the lookup key into getById (it survives renames; a better cache key than the slug).

import { loadGraph, loadPageBrief } from "@acme/content-types";
 
const g = loadGraph();
 
// a listing / index page — enumerate by label
const allProducts = g.byLabel("product");                        // every product page
 
// a detail page — build domain lists by the edge types you know
const id = loadPageBrief("/products/alfa-laval-sru")!.id;         // the stable handle
const applications = g.outNodes(id, "HAS_APPLICATION");           // build your own list, by edge type
const collections  = g.outNodes(id, "HAS_COLLECTION");            // …and another — no entities.csv, no array passing

Migrating off the row reader (loadRegistry → loadGraph)

The row-reconstruction reader (RegistryEntry / loadRegistry* and the slug-keyed helpers) is removed in the graph cleanup (§6.2) — running gtmesh types regenerates the package without it. If your SSG still calls it, move each call to its loadGraph() equivalent. The graph is loaded once and indexed, so these are lookups, not array scans:

The RegistryEntry fields that were derived at reconstruction move to the same edge reads — read them off the graph rather than a row:

Redirects need no change: loadRedirects() returns the same { from, to } list from the url/ALIAS_OF graph layer. It is not deprecated.

Entities — the entity table & facets (entities.ts) — deprecated

These deprecated readers reconstruct a slug-keyed table of entity relationships and their config-declared facet columns (taxonomy.facets); the same data now lives on entity nodes in the committed graph, read via loadGraph() above.

Assets — co-located images & documents (assets.ts + site.ts)

Resolve a bare asset filename to a URL, and ship the files. See Assets.

Site — config-derived constants (site.ts)

Projected from gtmesh.config.yaml by gtmesh types, so the SSG never re-declares engine policy.

Types

Generated per-schema interfaces (GuidePage, ProductPage, …), the PageType union, GraphNode / GraphEdge / GraphView, Entity, RegistryBrief, Redirect, Status, LoadOptions, PageBundle, Section, and RenderEnv — all re-exported from the package entry. (RegistryEntry / RegistryRow are removed — §6.2.)

Key files & flags

Related

• types — the command in full
• Lifecycle — how pages reach the committed graph the package reads