# Render Reference And Asset Manifest Contract

Markitect models render-aware structure before an optional renderer runs. The
contract is passive: it records units, requested references, static assets, and
source maps, but it does not assign final numbering, rewrite links, copy
assets, or validate renderer output directories.

## Contract Version

- `markitect.render.reference.v1`

The manifest kind is:

```text
render-reference-manifest
```

## Render Units

`RenderUnitReference` gives a stable identity to renderable content:

| Unit kind | Typical use |
| --- | --- |
| `section` | Headings and TOC entries. |
| `figure` | Images, charts, diagrams, and captions. |
| `table` | Markdown or generated tables. |
| `equation` | Math blocks or equation-like units. |
| `code-block` | Numbered or referenced code listings. |
| `custom` | Project-defined numbered units. |

The unit model may carry labels, captions, anchors, source spans, content
hashes, and numbering intent such as scope or sequence. It intentionally does
not carry final numbers.

## Cross-References And TOC Planning

`RenderCrossReference` represents a requested link from one source location to
a target render unit. It records the target unit and requested style, while the
renderer decides final label text, numbering, and URL rewriting.

`RenderTocEntry` records planned table-of-contents entries by unit id, title,
level, parent id, and order. The renderer owns final page numbers and links.

## Static Assets

`RenderAssetManifest` is a deterministic list of static assets referenced by
renderer source. Each `RenderAsset` records:

- source URI or source path
- name, media type, and extension
- digest when available
- logical role
- copy policy declaration
- renderer output reference placeholder
- provenance back to source spans or source adapter attachments

Supported copy policies are `copy`, `embed`, `link`, `preserve`, and `skip`.
They are declarations for downstream renderers. Core Markitect never copies the
asset.

`markitect-filter` may provide read-side attachment metadata, such as source
URI, path, media type, extension, digest, and attachment provenance. Markitect
can transform that metadata into a render asset entry without making
`markitect-filter` responsible for rendering.

## Source Maps

`RenderSourceMap` connects Markitect source spans or generated function outputs
to renderer units and artifact references. This is the bridge from deterministic
Markdown processing to renderer-owned artifacts:

```text
source span / function output -> render unit -> renderer source or artifact
```

The map can reference a Markitect source unit, a document function run, a
render unit id, an artifact id, or a renderer-owned artifact reference.

## Fake Renderer Integration

`RenderExportRequest` accepts an optional `render_manifest`. The built-in
`render.fake` adapter echoes the manifest id, asset manifest id, unit counts,
cross-reference count, TOC count, source-map count, and asset count into result
and artifact metadata. It still performs no external rendering and has no
filesystem or network side effects.

See `examples/render/render-reference-manifest.yaml` for a complete manifest
fixture.

## Repository Boundary

- `markitect-tool` owns these passive contracts and fake-renderer metadata
  integration.
- `markitect-filter` owns read-side source asset and attachment metadata.
- `markitect-quarkdown` owns concrete Quarkdown execution, final numbering,
  output paths, link rewriting, asset copying, and artifact validation.