Review: Tier 3 — Visual Authoring Tools (r3)

This round re-checks docs/designs/authoring/tier3-visual-tools.md against the current MAID codebase, with special attention to the r2 fixes the document claims to have incorporated.

Verification summary

Check	Result	Notes
1. Room export uses real canonical shape with top-level exits and _meta.schema	FAIL	The example now uses top-level exits and _meta.schema, but §4.8 still says that shape is the same format produced by @export, which is false in the current code.
2. Import honestly says it uses admin API, not loader pipeline	PASS	§4.8 now explicitly says import uses admin REST endpoints and is a different code path from maid data load.
3. Cross-surface sync limited to admin-API changes in v1; @dig bypass acknowledged	PASS	§3.5 and §18a.5 now clearly scope WS sync to admin-API mutations and require manual refresh for in-game builder changes.
4. NPC live preview gap is acknowledged or descoped	PASS	§6.3/§19 mark the preview API as a backend prerequisite and show a placeholder until it exists.
5. Role matrix matches actual permissions	PASS	§16.5 now correctly states MODERATOR (20) < BUILDER (30) and makes moderators view-only in the editor.
6. Executive summary matches v1 scope	PASS	The v1 summary now advertises tablet layout + collaboration basics, not PWA/review workflow.
7. localStorage is used consistently for v1 layout persistence	PASS	v1 sections consistently use localStorage; IndexedDB is deferred to post-v1/offline work.
8. Appendix B WebSocket message types are lowercase	PASS	Appendix B examples use lowercase underscore names such as editor_cursor, room_created, room_updated, room_deleted.
9. Balance dashboard explicitly depends on Tier 2 analyzers	PASS	§12 now states the dashboard is a Tier 3 presentation layer over a Tier 2 balance-analysis engine, with graceful degradation if Tier 2 is absent.
10. Zone vs Area terminology	PASS (good enough)	The glossary now distinguishes Zone from room area_id/area_name, which is directionally much clearer than prior rounds.

Issues

1) HIGH — §4.8 still misstates the relationship between visual-editor export and @export

• Section reference: §4.8, especially lines 1073-1076 and 1142-1185
• What’s wrong: The document now correctly shows the Tier 1 room authoring shape with top-level exits, and it separately explains that @export is structurally different. But the first export bullet still says the Tier 1 canonical format is the same format produced by the @export builder command. That is not true in the current code. @export emits { _meta: { schema }, rooms: [...] } with component data and tags only (packages/maid-stdlib/src/maid_stdlib/commands/building/export.py:141-152). It does not hoist room exits to top-level; the real loader-facing room shape does (packages/maid-engine/tests/fixtures/data/valid/rooms.yaml:1-19, packages/maid-engine/src/maid_engine/loader/entity_types.py:7-13).
• Why it matters: This is the core import/export contract for the visual editor. Leaving one subsection saying “same as @export” and the next subsection saying “@export is structurally different” will mislead whoever implements export normalization.
• Suggested fix: Rewrite the export bullet to say: the visual editor exports Tier 1 authoring format for loader compatibility, while @export is only a reference point for component serialization and must be normalized (especially exits) before writing authoring YAML.

Overall assessment

This is substantially better than the previous rounds. The admin-API-vs-loader distinction is now honest, the v1 cross-surface sync limitation is acknowledged, NPC live preview is framed as a backend gap, the role matrix matches code, the executive summary no longer overclaims PWA/review scope, and the layout persistence story is consistent.

However, I would not call this SHIP yet. There is still one important factual contradiction in the export section, and it sits in a critical part of the design.