# The Block Graph WebMCP API

Versioned static farm JSON is available at `/data/farms/v1/{edition}/catalogue.json`, `/{farmId}.json` and `/graph.json` beneath the edition directory. See `/data/farms/v1/README.md` for exact fields, filtering examples, schema 1.0.0 and candidate progression graph limitations. Discovery exposes these links in `farmJson`. `search_farms` adds optional exact resource/tool/station/output ID lists, rank bounds and default/any-layout filtering; `get_farm` includes the same shared object as `catalogueRecord`. Existing calls and source IDs remain valid. All requirement mappings are partial; the graph does not promise a feasible build order.

API version: **2.21.0**. Tools run in an open page on the static datasets shipped with the site.
The page registers them only when its secure browser context supports `document.modelContext.registerTool`.
Registration belongs to the top-level page; embedded farm previews do not duplicate the tool list.
There is no server-side MCP endpoint, background schedule runner or compatibility polyfill.
An external scheduled prompt must open the site in a supporting browser to call tools.

Read the [tool manifest and input schemas](./api.json), [readable changelog](./CHANGELOG.md), or [JSON changelog](./changelog.json).
Read the [agent conduct policy](./AGENT-POLICY.md), [policy JSON](./agent-policy.json), and [capability map](./capabilities.json) before using the tools.

## Conduct and capability discovery

`block_graph_get_api_info` includes the complete `agentPolicy`, explicit `capabilities` map and `policyCompatibility`.
The policy identifies allowed, prohibited and unethical agent conduct. Gameplay ethics are explicitly unspecified;
no ban or endorsement of particular Minecraft mechanics is implied.
Cloning The Block Graph site is prohibited and unethical. Proper, documented API use is allowed.
Credit **The Block Graph** by name with a link whenever using the site as a resource or using its APIs.
Discovery includes machine-readable credit instructions in `agentPolicy.attribution`; preserve upstream provenance as well.
API/policy 2.0.0 is a major conduct-policy change; the nine tools retain their existing call shapes.
Every response identifies `policyVersion` and `policyUrl`, including errors.
Callers may pin an exact stable `requiredPolicyVersion` (for example `2.0.0`). A mismatch returns
`POLICY_VERSION_MISMATCH` before loading content data. Discovery remains available and reports `matches: false`.
Omitting the pin reports `matches: null`. Matching a version is not proof that an agent read or followed the policy.

The capability map distinguishes supported operations, partial coverage and UI-only features. In particular,
standalone biome/trade queries, blueprint editing and saved-state controls are not fully exposed by these nine tools.
Follow the documented gaps; do not infer a callable capability from a page link or read-only result.
The static tools enforce their own inputs and execution boundaries; conduct and ethics remain agent responsibilities.

## Tools

| Tool | Purpose |
| --- | --- |
| `block_graph_get_api_info` | Discover versions, compatibility, tools, schemas and snapshots. |
| `block_graph_get_api_changes` | Read releases newer than `sinceVersion`, with breaking flags and migration guidance. |
| `block_graph_search_resources` | Find exact block, item and entity keys. |
| `block_graph_get_resource` | Read registry details, provenance and related connections. |
| `block_graph_get_acquisition_paths` | Browse source-indexed routes and candidate farms, retaining evidence. |
| `block_graph_get_recipes` | Read output recipes, grids, quantities, stations and source definitions. |
| `block_graph_plan_recipes` | Plan counted goals against explicit starting inventory and base blocks. |
| `block_graph_search_farms` | Find edition-available farms by text, candidate output or catalogue dimension. |
| `block_graph_get_farm` | Read setup, operation modes, review status and available blueprint/materials. |

## Stable response envelope

Every result is a JSON-serializable object with:

```json
{
  "ok": true,
  "apiVersion": "2.0.0",
  "policyVersion": "2.0.0",
  "policyUrl": "/webmcp/agent-policy.json",
  "buildNumber": null,
  "releaseDate": null,
  "builtAt": null,
  "environment": "development",
  "dataset": {"edition": "java", "version": "26.2", "sourceRevision": "pinned-source-commit"},
  "data": {}
}
```

Released builds use the same actual build number, UTC release date and build timestamp as the site footer and `/release.json`.
Development results have null build fields; the example is a development response, and its revision is a placeholder.
Discovery results have `dataset: null` and list both snapshots in `data.datasets`.
Failures replace `data` with `error: {code, message}` while retaining all metadata.

Error codes: `INVALID_INPUT`, `INCOMPATIBLE_API`, `RESOURCE_NOT_FOUND`, `FARM_NOT_FOUND`, `EDITION_UNAVAILABLE`,
`DATA_UNAVAILABLE`, `CANCELLED`, `TIME_LIMIT`, `PLANNING_FAILED`, `POLICY_VERSION_MISMATCH`.

## Version checks for scripts and scheduled prompts

1. Call `block_graph_get_api_info` with `{"requiredApiRange":"^2.0.0","requiredPolicyVersion":"2.0.0"}`.
2. Require `data.compatibility.compatible` to be true before depending on the contract.
3. Include `requiredApiRange` on subsequent calls. Incompatible calls fail before loading content data.
4. Call `block_graph_get_api_changes` with `{"sinceVersion":"1.0.0"}` to inspect newer changes.
5. Read `agentPolicy` and capability gaps; if a pinned policy changed, review its rules before continuing.

Only stable full versions and exact, caret or tilde ranges are accepted. Unsupported range syntax is an `INVALID_INPUT` error.
Caret follows semver compatibility (`^1.2.3` permits versions below `2.0.0`; `^0.2.3` below `0.3.0`; `^0.0.3` only that patch).
Tilde permits compatible patches within the selected minor version. Prerelease versions are not published by this API.
Discovery remains available even for an incompatible valid range, and reports `compatible: false`.
Without a requested range, it reports `compatible: null`.
`sinceVersion` is exclusive; equal versions return no releases, and future versions are rejected.

API versions describe the interface; `dataset.version` describes Minecraft; build metadata identifies the site artifact.
Different data or a new build can produce different content under the same compatible API contract.

## Content examples

```json
{"edition":"java","query":"crafting table","kind":"item","requiredApiRange":"^2.0.0"}
```

Use the returned exact key in `get_resource`, `get_acquisition_paths` or `get_recipes` as `resourceKey`.
Resource keys include edition and kind, for example `java:item:minecraft:crafting_table`.
Farm output filtering uses `outputResourceKey`; farm detail uses `farmId` from its search results.

```json
{
  "edition":"java",
  "requiredApiRange":"^2.0.0",
  "goals":[{"key":"java:item:minecraft:crafting_table","count":1}],
  "inventory":{"java:item:minecraft:oak_planks":4},
  "base":{}
}
```

Planning accepts up to 20 goals and 200 rows each of inventory and base blocks, with whole quantities from 1 to 999999.
Inventory is consumed across goals once; base entries describe available blocks in the existing planner model.
The default biome is the selected snapshot's plains; an explicit biome must be an exact edition-qualified biome key.
The solver searches at most 50000 states, with a 10-second worker deadline. Cancellation terminates the worker.
`complete` means a feasible exact-recipe plan; `needs-input` or `search-limit` retains unresolved goals and source-backed requirements.
These do not establish unobtainability or a minimum-cost plan. Requirements in unresolved routes are not calculated shortages.

Search, acquisition and recipe lists accept `offset` and `limit` (default 0 and 20, maximum page size 100).
Results include `items`, `total`, `offset`, `limit` and `nextOffset` (null at the end). Ordering is deterministic within a build.

Farm search items and farm details also include `group: {id, label, variants: [{id, label, url}]}`.
Groups use the same domain function as the farm UI and list only variants available in the requested edition.
Search accepts shared group names but still returns individual farms; IDs, URLs and pagination remain stable.
Call `block_graph_get_farm` with a variant's original `id` for its own blueprint, outputs, conditions and evidence.
Variant choice is separate from an individual farm's numeric operation `mode`. Group membership does not imply identical mechanics or interchangeable layouts.

Farm search items and details include `canonicalFarmId`. For equivalent source records, `group.variants` contains only the displayed canonical farm, while optional `group.aliases: [{id, label, url}]` retains the other source records.
Search items also include `hint: {tldr, mechanism}`; farm details include `hint: {tldr, mechanism, needs, sources}`. API 2.4.0 adds optional `hint.production` (gross harvest text with its baseline) and `hint.exceptions` (string array). The UI shows the action summary once, followed by Produces, Requires and optional Exceptions; the mechanism field remains available for API clients. Do not assume that unquantified farms have reviewed drop ranges.
Hints are shared with the UI, preserve important edition differences, and describe the built-in rule or behavior behind production. They are concise explanations, not full build plans or in-game verification. Use `sources` for detailed references; original `conditions`, `operation` and `blueprint` fields remain unchanged.
Deduplicate equivalent results by `canonicalFarmId`; call that ID for the displayed farm. Legacy-ID requests still return the original record fields and working URL for provenance. Genuine choices such as Manual/Automatic composting remain separate variants.
`get_recipes` returns the shared recipe-method presentation including original source definitions and hashes.
Acquisition paths retain the shared index entries. If the syntactic index omitted a recipe's output,
the shared recipe reader adds a `parsed recipe output` path with its recipe, station binding and original source/hash.
Alternatives, ingredient tags, item data, grids and conditions remain explicit; similar-looking woods are not inferred interchangeable.

Farm search defaults to this edition's available farms. Dimension describes catalogue origin, not where a farm may operate.
Output-resource matches use the same candidate-matching logic as acquisition paths and remain unverified candidates.
Farm details return the existing default blueprint or null, including construction review status and known gaps.
Diagram-only cells are not automatically materials; the existing blueprint material calculator supplies the material list.
Operation modes are zero-based: omit `mode` first to discover available mode labels in `operation.modes`.
Construction review does not claim an in-game test, and absent operation/blueprint data stays null.

The tools read shipped data and compute results. They do not modify saved plans, blueprint drafts, edition preferences or navigation.
Returned page links open the related view; resource links open the resource catalogue for the selected edition.

## Maintenance

`api.json` is the source of registered names, descriptions and input schemas. Update it and both changelog formats together.
`capabilities.json` maps current site routes to tool coverage and explicit gaps.
`agent-policy.json` is the owner-editable policy; the readable page is generated from it.
Classify input, response shape, error and documented behavior changes using semver before release.
Add an entry with `version`, `date`, `breaking`, `affectedTools`, `changes` and `migration` to `changelog.json`.
Keep `block_graph_get_api_info` as the discovery entry point across major versions.
Normal checks and builds run `npm run webmcp:check`: source changes require a recorded capability and version-impact review.
Use `npm run webmcp:review -- --impact minor --reason "describe the reviewed change and its compatibility"` after updating a compatible feature release.
Use `none` only with a specific explanation for a change that has no API, policy or capability impact.
The review command generates the policy page, saves a new release contract without overwriting old contracts, and records source hashes.
These checks detect changes and structural compatibility problems; a maintainer must judge semantic behavior and ethics.
Run `npm test`, `npm run typecheck`, `npm run build`, and the WebMCP browser checks described in the repository documentation before shipping.

Implementation reference: [Chrome WebMCP imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api).

### Compact layouts and space (2.5.0)

`blueprint` is the compact supported default. It adds `space` and `layouts`; each layout contains `id`, `label` and its complete `blueprint`, with materials and space. Empty layouts means no additional spatial choice is serialized; some specialist and pre-existing version controls remain UI-only as described in the capability gaps. Original IDs and input contracts remain valid. Defaults can have different dimensions, materials, automation and harvest eligibility; read their caption, conditions and conditional hint.

`space.occupiedSpaces` counts unique non-air block cells, including fluids and waterlogged plants once. Empty guides do not count. `space.modelVolume.known` sums the union of cuboid model parts in block units; slabs and stairs contribute fractions. `unmeasuredSpaces` identifies non-cuboid or missing geometry. This is a rendering-model measure, not collision volume or the solid pixels of foliage. `space.bounds` reports the separate enclosing dimensions/volume, including air. No global-minimum or in-game validation claim is made. Custom diagrams can be partial views and are not a full-farm construction total.

### Animal species specializations (2.6.0)

Animal breeding has 22 species under one operation family; milking/stew, egg incubation and squid ink harvesting also share groups. `group.selectionKind: "specialization"` and `group.specializations` identify species choices. The legacy `variants` member-link array is retained for compatible clients. Wall height, area, food and habitat are selected-species requirements, not independent variants. Original IDs, routes, evidence and species operations remain accessible.

Animal `blueprint.enclosure` and each serialized layout’s enclosure report `interiorFootprint`, `boundary`, `wallBlockLayers` and `roofed`. `minimumVerified: false` explicitly distinguishes this illustrated example from an established engine minimum. A fence layer is not a claim that its collision height is one block. These properties do not establish full free interior volume, safety or in-game validity. Individual API dimension filtering retains original species origins; the UI additionally keeps the cross-origin breeding family discoverable under Nether.

### Generic construction and chicken protection (2.7.0)

Chicken egg collection keeps its `compact` layout ID (labelled Basic), adds `protected`, and retains `expanded`. The protected layout closes its walls and roof, keeps a non-spawnable glass floor and routes two hoppers to an external chest. Read each layout's conditions; open fences only contain chickens and do not exclude predators. Exact builds remain pending in-game verification.

`material:any_solid_block` is a logical construction category, not a Minecraft item or vanilla tag. Its stable, non-damaging full cubes are represented by `visual:any_solid_block` cells, drawn as glass. The inventory label states the constraint and `variants` gives non-exhaustive concrete examples. Choose actual blocks for these cells; do not pass the category to a game command. Explicit `minecraft:glass` floor cells in the protected layout retain their non-spawning requirement and are counted separately.

### Skeleton and creeper specializations (2.8.0)

`mob-skeleton` and `mob-creeper` share group `skeleton-creeper-farming`, labelled Skeleton & creeper farming, with `selectionKind: specialization`. Original IDs, routes, output focus, source evidence and safety conditions remain available. Querying either target selects it while retaining both choices. Their shared dark-room layout spawns mixed mobs; a target choice does not make the farm species-exclusive. Refresh cached grouping metadata and read each specialization's conditions.

### Undead mob specializations (2.9.0)

`mob-zombie`, `mob-husk`, `mob-stray` and `mob-bogged` share `undead-mob-farming`, labelled Undead mob farming, with species specializations. Each original record, route, output, evidence and spawning/safety condition remains available. The selected target retains dark-room versus open-sky spawning, desert/cold/swamp habitat, covered stray water sources and conversion/arrow precautions. Refresh cached group metadata; target selection does not exclude other mobs.

### Batch lava chicken cooker (2.10.0)

`chicken-lava` adds a player-operated cooker, grouped with `chicken-eggs` under Chicken farming. `search_farms` preserves method selection; `get_farm` returns the cooker blueprint, materials, occupied-space and volume measurements, cooked outputs, egg input and manual hatching/lava requirements. Existing IDs and fields remain. Refresh cached groups and farm records. The batch design has no automatic age detector, is not lossless, and still needs an in-game check in each pinned edition.

### Flat sponge drying methods (2.11.0)

`get_farm` for `review-wet-sponge-drying` retains `compact` and `expanded` furnace layout IDs and adds `nether` plus Bedrock-only `desert`. Each blueprint may include optional `hint` copy for its operation, production and requirements. Refresh cached layout lists; use their returned IDs. Legacy numeric `mode` inputs remain unchanged and do not index this layout list. Java does not expose desert placement.

### Copper golem sorter (2.12.0)

`copper-golem-sorter` is a storage utility with nine single-chest positions in a 3×3 wall. Search and detail tools expose its copper input, lowered golem work cell, resources, measurements, sample-item and capacity requirements, optional waxing, sources and pending in-game reach checks. It rearranges supplied items; it is not a renewable source of those items. Refresh farm caches; existing IDs and inputs are unchanged.

### Farm requirements and automation logic (2.13.0)

`get_farm` keeps `blueprint.materials.entries` and `note`, and adds `materials.groups`: nonempty groups with `category` (`resources`, `tools`, `stations`), `label` and the original requirement entries. Counts, choices and Silk Touch requirements retain their meaning. An optional entry `category` overrides the shared classifier for a contextual tool, such as a bucket used to fill a large pool. Groups partition requirements; do not sum entries and groups together. Tools include implements and collection containers; stations include furnaces, composters, cauldrons and other work blocks. Filled buckets normally supply resources unless explicitly identified as reusable site-filling tools. Classification does not imply an item is never consumed or loses no durability.

Farm details add nullable `automationLogic`, and each available layout blueprint supplies its own value. The object contains `kind` (`redstone`, `item-flow`, `entity`), `status` (`illustrated`, `incomplete`, `unmapped`), a short `sequence`, repeat/reset `control`, and `sources`. It describes the represented build, not every possible automation for that resource. The shared definitions cover separate chicken controls, manual honey harvesting, spider/witch dispenser flushing, incomplete brittle-ice reconstruction, unpowered hopper processing/collection and copper golem sorting. No timer, sensor or working circuit is inferred from a parts list. `illustrated` does not mean tested in-game. Null means no automation is represented; it does not prove automation is impossible. Custom schematic geometry and material serialization remain partial where `blueprint` is null.

Migration: refresh cached farm details and layout lists. Existing material entries and input contracts remain valid; clients may adopt category groups and core logic independently. Agent policy remains 2.0.0.

### Required Progress and sorting (2.14.0)

The UI presents this as the final `Progress` row in the farm facts list, for example `Day One (1)`. Specific prerequisites remain under Requires; rank reasoning and counted build cost appear in a hover/focus tooltip. This display format does not change API rank indices, labels or requirement data.

Discovery adds `farmProgress: {modelVersion: 1, ranks: [{index, label}], rankMeaning}`. The 1–11 integer indices are stable sort keys; labels are editable presentation text. Search and detail return `progress` for each source record's default example. Each detail layout blueprint has its own `progress`. Use `sortBy: "progress"` and optional `sortDirection: "asc" | "desc"` on farm search; default `sortBy: "name"` and ascending order preserve existing behavior. Numeric progression ties use ascending farm name and source ID, making pagination deterministic.

`progress` contains `rank`, `label`, `modelVersion`, `assessment` (`estimate` or `incomplete`), minimum listed `tools`, optional usual ore-mining `toolSupply` and its bypass alternatives, typed `gates` with Source/Site/Build/Access scope, and `requires` booleans for Nether access, End access, prior Ender Dragon victory and diamond harvesting tools. Gates can specify `anyOf` alternatives. Sources, reasons, notes and `cost` keep the estimate inspectable. Cost includes the available example's occupied spaces, listed starting units/type count, sourcing areas and workload floor; operation-only costs are null. Starting units include tools, stations and placement/input allowances; they are not expanded raw recipe costs or ongoing fuel consumption. A grown canopy is not charged as starting construction.

The rank is the maximum of an explicit reviewed operation profile, gear/material floor, real access gates and starting-workload/variety floors. Workload floors: at most 32 units = 1; at most 128 = 2; at most 512 = 3; at most 2,048 = 4; above 2,048 = 10. More than 1,024 units across at least three sourcing areas gives floor 11. More than five/nine/fifteen requirement types give floors 2/3/4. This is an editorial ordering, not elapsed time, guaranteed popularity, a proof of earliest possible completion or a personalized inventory check.

Minimum illustrated harvesting equipment is distinct from usual tools for mining its raw ingredients. Diamond tools are needed for the illustrated obsidian harvest; entering the Nether does not imply a diamond pickaxe because portal obsidian can be cast or obtained elsewhere. Crop hydration can reuse existing water. Optional or explicitly excluded Silk Touch is not a gate. Nether wart's starter source does not restrict its growing dimension. Stronghold silverfish do not need an active End portal. Outer-island chorus and shulker access does not itself require a dragon victory; the illustrated repeat dragon and manual End-platform return loops do. Normal self-supplied End access includes Nether blaze-powder sourcing; an already active portal bypasses that step. Template sources and other alternate methods can change these requirements.

Migration: existing farm IDs, required input contracts and default search ordering remain unchanged. Refresh farm/layout caches; compare integer ranks rather than their text labels. Catalogue group sorting uses the initially shown member and default build, while selecting a specialization/layout updates its displayed requirements without automatically moving surrounding cards. Policy remains 2.0.0.

### Typed farm outcomes (2.15.0)

Farm search and detail return `produces`; detail also includes `hint.produces` for the shared hint renderer. The original `outputs` string list and `hint.production` yield/eligibility text are retained.

Each outcome has `kind`, semantic `id`, readable `label` and `icon`. Kinds are `item`, `entity`, `experience`, `category`, `block-state`, `access` and `none`. Optional `condition` describes eligibility; `relation: alternative` separates mutually alternative outcomes. Categories use `blockgraph:` identities and representative artwork, not exhaustive loot tables.

Icons are `{kind: resource, id, display?: block, representative?: true}`, `{kind: entity, name}`, `{kind: experience}` or `{kind: none}`. Resource icon IDs resolve artwork and may use sprite aliases such as `minecraft:melon_block`; use the outcome's `id` for resource identity. An icon does not imply that its depicted item is itself produced. Render `hint.production` once where present to preserve exact quantities, baselines and edition-specific eligibility.

### Farm versions and verification data (2.16.0)

Farm search and detail include `version: {date: YYYY-MM-DD, change: positive integer}` and `lastVerified`. These are the same persisted fields carried by the shared and per-edition catalogue data. Farm tracking begins at Change 1 on 2026-10-17. Each original source ID has its own counter; layout alternatives within a farm share that farm's revision. The date is UTC. Counters continue across dates and are independent of Minecraft versions and site build numbers. Ordinary builds do not increment them.

`lastVerified` starts null for every farm and is not rendered in the farm UI. A future actual in-game verification can record `{date, change, edition, gameVersion}`. That describes the latest test of that exact farm revision in the named edition/version, not proof for other editions or later changes. Updating the farm preserves an older verification event instead of marking the new revision verified. Construction review and source/browser checks do not set this field. See `docs/farm-versioning.md` in the source for the maintenance command and baseline rules.

### Embed configuration (UI-only)

Farm catalogue use-subgroup headings include representative Minecraft item icons in a shared UI component. Names, category assignments, counts, filtering and farm identities are unchanged. The decoration adds no WebMCP field or tool; category artwork does not imply an additional output.

The Blueprint only / Farm and instructions content view is selected with grouped wireframe-cube/checklist icon buttons above the preview on the right. The buttons retain accessible names, title tooltips, selected state and 44 px targets. They retain the same `embed=1` / `embed=card` URL values; selectors within the embedded farm retain their blueprint-first order.

The desktop Embed dialog places the preview on the left and authoring controls/code on the right, with independent control-column scrolling. At narrow widths the controls stack below the preview. The preview precedes controls in DOM order, and source-card geometry and selection remain stable. This layout changes no tool or URL contract.

Both farm embed modes paint their iframe canvas, body and application surface with the selected theme's paper/ink tokens. Blueprint-only card unwrapping does not expose the main site's textured page background. This presentation fix preserves scene artwork, query behavior, host appearance and API contracts.

Farm embed documents omit the site's side-only borders, outer shadow and width caps and retain even padding on all four sides. The authoring preview shows the live iframe inside a Lorem ipsum sample host article with a source link; the sample page follows the dialog theme independently of the selected iframe theme. This is preview-only context and is not included in copied embed code. URLs, dimensions, API schemas and farm data are unchanged.

Both farm embed modes include their own small crafting-table brand mark and The Block Graph homepage link inside the iframe. The link opens a new tab with `noopener noreferrer`. Attribution is at the bottom for short content and follows longer content without overlays; it is not duplicated outside the sample widget. This is UI attribution, not a change to API conduct policy, tool schemas or farm data.

The embed authoring dialog offers Copy image and Save PNG. These UI-only actions render the current same-origin widget locally, including its full content, selected theme, preview width and brand credit, while excluding the sample host article and controls. Copy requires browser image clipboard support and permission; Save PNG is the download fallback. Rendering loads on demand, retains live scene state, and bounds canvas dimensions/memory. No WebMCP tool reads the clipboard, captures screenshots or exports images; API schemas, policy, capability coverage and farm records are unchanged.

Embed dimensions use compact text inputs and indexed common-size sliders, including 100% and auto. Height defaults to auto and fits the full widget through the static `/embed-resize.js` host helper and an opt-in `height=auto` fragment setting (legacy query settings remain readable). It updates for content, loaded assets and responsive width changes; explicit fixed heights remain available. Width auto retains intrinsic CSS sizing, and percentage sizing depends on the host containing block. Invalid drafts retain the last valid size. The height protocol validates the iframe's origin and source window and accepts finite numeric heights from 1–100000 CSS px. Auto-height copied markup includes the helper script, which must be permitted by the host's script policy; dynamically inserted HTML needs a normal script element for the helper. See [embed auto-height](../../docs/embed-auto-height.md). This browser-only integration adds no WebMCP tool fields or screenshot/DOM-control capabilities; API and policy contracts remain unchanged.

The repository's `docs/embed-input-security.md` records the input review. UI controls do not invoke an AI model. Dimensions pass bounded lexical checks before native CSS validation, dropdowns retain known values, generated attributes/template metacharacters are escaped, and executable iframe URL schemes are rejected. This is code/data injection protection, not a guarantee about how an external AI consumer treats page content; existing WebMCP schemas, policy and capability coverage remain unchanged.

Variable-driven theme instructions and generated template comments document type `string` and exact values `"day"`, `"night"`, `"auto"`. The UI lists each value's behavior from shared typed option metadata. Values are lowercase/case-sensitive; other values follow the system preference. This documents existing embed URL behavior without adding a WebMCP field or changing the API contract.

The dialog reuses the farm page's specialization/variant selector and option metadata: icon-and-label buttons for small sets, and a synchronized icon grid/name dropdown for larger sets. Embed authoring selectors appear to the right on desktop and below on narrow screens; selectors within the embedded farm retain their blueprint-first layout. These controls update only the embed preview and generated code; source-card selection and API group membership are unchanged.

Embed URLs accept `theme=day`, `theme=night` or `theme=auto` when `embed=1` or `embed=card`. Explicit Day/Night values override saved appearance for that iframe only; `auto` and other values follow `prefers-color-scheme`. No saved theme is written. Omitting `theme` preserves the existing saved/system preference behavior. The dialog offers fixed HTML, a JavaScript template with `YOUR_THEME_VARIABLE` and a generic server-template placeholder `{{ THEME_VARIABLE }}`. JavaScript yields an `embed` HTML string and normalizes other values to `auto`; replace server placeholders using your engine's URL encoding and HTML attribute escaping. The variable-mode preview uses a separately selected example value. These are UI integration examples; WebMCP schemas and tool versions are unchanged.

The Embed dialog previews the exact iframe URL and dimensions used in its copyable code. Farm embeds retain `embed=1` for blueprint-only views and add `embed=card` for the compact farm card with instructions and references. Supported shared blueprint layouts can be initialized with `layout=<layout-id>`; unknown layout IDs fall back to the default. Available farm specializations use their existing individual farm URLs. Custom interactive controls remain inside their widgets; not every custom layout has a URL selector. Trading embeds preserve their existing profession, biome and rules parameters. These configuration controls remain UI-only under the existing interactive-view capability gap; API input/output schemas and farm blueprint data are unchanged.

### Fish resident visualization

Upward-facing block viewers also use a decorative upper-right sun or moon according to the page's Day/Night theme. This UI-only direction cue is separate from blocks, materials, gameplay time and farm conditions; it does not change the scene or API format.

The four fish-harvesting views render a supplied live fish as a textured mesh within the block viewer. It shares the scene camera and zoom, remains separate from placed blocks/material quantities, and is removed by the capture or harvest control. This custom resident layer and its interactive state are UI-only, within the existing custom-schematic capability gap. The block-only blueprint/editor scene format and API contracts are unchanged. A displayed fish is not a spawning simulation or evidence of in-game verification.

New embed code writes browser-only settings (`embed`, `theme`, `layout`, `height`, `profession`, `biome`, `rules`) into the URL fragment, for example `/farms/java/crop-wheat/#embed=1&theme=night`. Legacy query links still work; fragment settings take precedence. Only the static document path and any unrelated query keys reach the server. Live fragment updates preserve the preview document. This affects UI embed authoring only: existing API result URLs, schemas, tool versions and capability classifications remain unchanged.

The sorter includes copper-block and carved-pumpkin construction inputs, reuses the resulting copper chest, and encloses the living golem. Its `compact` layout remains the default; `minecart` adds a positioning method, cart and temporary loading materials. Neither layout has verified in-game reach to all nine destinations.

Farm Produces rows use clean typed labels and quantified production text. Optional `hint.productionNotes` contains the shared, visible Yield notes: harvest baselines, Fortune/Looting and Silk Touch modifiers, chance drops, collection alternatives, kill attribution, fuel and net gain. Typed `produces.condition` remains available. Use these fields instead of parsing production prose; labels and quantities no longer repeat their qualifiers. Selected-layout hints retain their own notes. Original source output strings, resource identities, references and edition differences remain intact.

Farm revision labels appear at the bottom of the content area on catalogue/detail pages and inside both embed modes, above the widget's brand attribution. The selected farm's date/change and data-only verification records are unchanged; this presentation move adds no API field, policy change or farm revision.

Zombie iron includes captured and spawner seed-source layouts. Optional `blueprint.residents` describes live mobs (`id`, `name`, model-center `at` in block units, quarter-turn `turn`) separately from placed blocks and supplied materials. The spawner option includes the proposed room, channel and gated inlet. Optional `blueprint.floorGuide` (`min`, `max`, `label`) and `blueprint.transferPath` (`points`, `label`) describe spacing and entity-travel annotations in scene block units. They do not count as blocks or materials and do not simulate fluids or verify gameplay.