refactoring of cmaps, widgets, etc.

static/cmap/README.md

@@ -12,9 +12,26 @@ same hit-test and drag lifecycle as selection, so it does not depend on a DOM
 `model/concept-repository.js` owns shared concepts, semantic concept relations
 and concept ownership. `model/concept-map.js` owns one map's concept
 placements, linking phrases, connectors, metadata and presentation values.
-Neither model module contains DOM or drawing-engine objects.
+`model/cmap-repository.js` owns the server boundary: it decodes stored CMaps,
+normalizes legacy concept identities and converts backend documents to and
+from `CmapModel`. It is the only browser-side CMap model module that knows the
+`/api/cmaps` routes. `model/appearance.js` owns the shared named styles, colour
+palette, validation and style matching. `model/appearance-repository.js`
+serializes that model through the appearance API. `model/settings-repository.js`
+owns the wiki start CMap and the authenticated user's A4-guide and
+per-CMap-context zoom settings. `model/people-repository.js` is the server
+boundary for the people referenced by concept tags.
+The repository objects keep only an in-memory session copy; the backend remains
+authoritative. None of these model modules contains DOM or drawing-engine
+objects, and CMap state is not persisted in browser storage.
 
 `cmap-view.js` owns the canvas and the concrete `cmap.js` drawing instance.
+`view/appearance-editor.js` presents the appearance model in the concept dialog
+and coordinates explicit style and palette changes with its repository.
+The concrete dialog controllers live in `../js/wiki/cmap/dialogs/`. They own
+their fields, validation and browser events. The workspace supplies the active
+CMap and performs editor transitions, while the controllers use repository
+APIs for stored CMaps and people instead of calling backend routes directly.
 `cmap-racket-wiki.js` contains the wiki-specific editor controller, selection
 state, content-based initial sizing, resize and relation controls. Its view
 records connect pure model ids to drawing nodes without making those nodes part
@@ -59,12 +76,19 @@ metadata remain intact, but its document no longer depends on the parent CMap.
 
 `toDocument` and `loadDocument` round-trip the complete editor model: items,
 formatting, positions, connectors, recursive submap membership and promoted
-map references. The wiki host persists this JSON document through its CMap API.
+map references. The public `currentModel`, `loadModel` and `replaceModel`
+methods let the workspace pass complete domain models to and from the editor.
+The CMap repository, rather than the workspace, persists those models.
 
 ## JSON interchange
 
-`/js/wiki/cmap/interchange.js` implements the versioned `racket-wiki-cmap-bundle`
-format. A bundle mirrors the normalized database model: `cmaps[]` contains the
+`model/interchange.js` defines and validates the versioned
+`racket-wiki-cmap-bundle` format. `model/json-exporter.js` builds complete bundles
+through `CmapRepository` and the supplied page and attachment loaders.
+`model/json-importer.js` reads those bundles, stores CMaps through the same
+repository and performs the required page and attachment writes. The workspace
+decides only how conflicts are presented to the user.
+A bundle mirrors the normalized database model: `cmaps[]` contains the
 complete placement and presentation document, `concepts[]` contains shared
 content once per UUID, and `pages[]` contains the current Markdown, tags and
 referenced attachments of linked wiki and explanation pages. Attachments retain
@@ -85,6 +109,13 @@ a temporary identity into a UUID through the central Racket UUID helper. UUIDs
 already present in an export remain unchanged. Imported CMap slugs likewise
 remain unchanged.
 
+`model/markdown-exporter.js` reads stored models through `CmapRepository` but
+produces a readable
+report instead of an importable bundle. It is independent of the JSON
+exporter because the report follows linked maps and optional wiki pages for a
+different purpose. Additional output formats can therefore be implemented as
+separate exporters without adding format-specific code to the workspace.
+
 The editor keeps up to one hundred complete document states for Undo and Redo.
 One drag or resize gesture forms one history step. The public `undo`, `redo`,
 `canUndo`, `canRedo` and `resetHistory` methods are also used by the wiki host