npm package: @nuucognition/mesh-core
Description: Core Mesh SDK — storage-agnostic, browser-safe types and operations for building indexes, resolving links, and serializing meshes.
Latest version: 1.0.0

# @nuucognition/mesh-core

Core Mesh SDK — storage-agnostic, browser-safe types and operations for building indexes, resolving links, and serializing meshes.

## What it provides

| Category | APIs |
|----------|------|
| Document processing | `parseMeshDocument`, `normalizeDocument`, `parseFrontmatter` |
| Mesh building | `buildMesh`, `createMesh`, `createBlob`, `createHydrationContext` |
| Index computation | `computeBacklinks`, `computeTagIndex`, `computeBlobNameIndex` |
| Resolution | `resolveLink`, `resolveEmbed` |
| Loading | `loadIndex`, `loadContent`, `loadBlobData`, `loadDocumentView`, `loadSnapshots` |
| Selection | `selectDocuments`, `selectDocumentsWhere`, `expandSelection` |
| Wire format | `snapshotToWireFormat`, `wireFormatToSnapshot` |
| Validation | `validateMesh`, `detectCaseCollisions`, `lintMesh` |
| Transactions | `createTransaction`, `filterTransactionsByDocument`, `operationTouchesDocument` |
| Utilities | `extractWikiLinks`, `extractWikiEmbeds`, `extractExtension`, `titleFromPath` |

## Key concepts

| Type | Role |
|------|------|
| `MeshDocument` | Index-only metadata for a markdown document (id, title, tags, links, embeds) |
| `MeshDocumentSnapshot` | Document + content + hashes for transport |
| `MeshDocumentView` | Cold-start render payload with resolved links and backlinks |
| `MeshBlob` | Binary asset metadata keyed by `BlobKey` (`name.type`) |
| `MeshSnapshot` | Full mesh export payload (v0.3) |
| `Mesh` | Hydrated runtime structure: documents Map, blobs Map, indexes |
| `MeshReadAdapter` / `MeshWriteAdapter` | Interfaces for storage backends |

## Quick start

```ts
import { buildMesh, loadIndex, resolveLink } from "@nuucognition/mesh-core"
import type { MeshReadAdapter } from "@nuucognition/mesh-core"

const adapter: MeshReadAdapter = /* ... */
const { documents, blobs } = await loadIndex(adapter)
const mesh = buildMesh({ documents, blobs })

const result = resolveLink(mesh, "Home")
// result.status: "resolved" | "missing" | "ambiguous"
```

## Package layout

```
src/
  types/        Type definitions (mesh.ts, diagnostics.ts)
  document/     Document parsing (parse.ts, frontmatter.ts, content.ts)
  mesh/         Mesh building & resolution (build.ts, load.ts, validation.ts, selection.ts)
  wire/         Wire format serialization (format.ts)
  transactions/ Transaction creation and filtering
  utils/        Wikiref extraction, embed types, hashing, UUIDs
```

## Dependency graph

This is the foundation package — everything else depends on it.

```
mesh-core
  ^-- mesh-ops          (mutations)
  ^-- mesh-adapter-fs    (filesystem)
  ^-- mesh-convex-component (Convex storage)
  ^-- mesh-adapter-convex (bridge)
```

## Runtime strategies

See `docs/mesh/runtime-strategies.md` for Strategy A/B/C and cold-start usage.

## Related packages

- `@nuucognition/mesh-adapter-fs` — filesystem scanning and loading
- `@nuucognition/mesh-convex-component` — Convex storage backend
- `@nuucognition/mesh-adapter-convex` — bridge (core + Convex adapter)
- `@nuucognition/mesh-ops` — mutation operations (rename, wiki reference updates)