# mmo.client — Files needing more documentation
Produced alongside [SECURITY_REVIEW.md](SECURITY_REVIEW.md) by reading every `.js` file under `src/js/`, every `.scss` file under `src/sass/`, and every `.jhs` file under `src/customElements/` (48 JS files, ~28 Sass files, 42 `.jhs` files). Rated **good** / **partial** / **poor** / **none** based on whether the public API (classes, exported functions, non-trivial methods) has JSDoc/`///`-doc explaining purpose, params, and return values — not whether the code is self-evident from naming alone.
Overall picture: **the `.jhs` custom elements are, on the whole, well documented** (every one has at least a class-level docblock) — the real gaps are concentrated in a handful of `src/js/core` utility files and almost the entire `src/sass/classes/` + `src/sass/styles/` directories.
## Priority 1 — `poor`/`none` JS files (fix first; these are widely-depended-on utilities)
| File | Gap |
|---|---|
| [`src/js/core/Storage.js`](../src/js/core/Storage.js) | Only non-JSDoc block comments, no class-level description, no return types. Central enough (wraps `localStorage`/`sessionStorage` for entity persistence) to deserve full JSDoc — also flagged in the security review (§12) for a missing usage warning about sensitive data. |
| [`src/js/svg/Svg.js`](../src/js/svg/Svg.js) | Only a few instance fields have inline comments; `zoomBy`, `focus`, `select`, `allowSelection` (the actual public interactive API) are undocumented. |
| [`src/js/inputs/Press.js`](../src/js/inputs/Press.js) | No JSDoc beyond a one-line class comment; carries a `REDO not working` TODO that should be either resolved or turned into a tracked issue. |
| [`src/js/inputs/{Mouse,Pointer,Touch,TouchMouse}.js`](../src/js/inputs/) | Only class-level one-liners; each is small, but the `alias` table each defines (which native events map to the unified gesture events) is exactly the kind of thing worth one sentence per file. |
| [`src/js/inputs/inputs.js`](../src/js/inputs/inputs.js) | No JSDoc on `register()`/`$()`, the two functions other code actually calls into. |
| [`src/js/Error.js`](../src/js/Error.js) | The custom error hierarchy (`MMO.Error`, `MMO.PathError`, `MMO.RequestError`, ...) has no JSDoc; `PathError.getValidPath()`/`getInvalidPath()`/`value` (its distinguishing public API) are undocumented. |
| [`src/js/config.js`](../src/js/config.js) | No JSDoc (acceptable as a mock/example config, but a one-line header noting "this is a dev-mode placeholder, replaced by server-rendered config at runtime" would prevent someone mistaking it for the real shape contract). |
## Priority 2 — `partial` JS files (fine to defer, but each has a real public-API hole)
- [`src/js/core/functions/core.js`](../src/js/core/functions/core.js) — `preventPropagation`, `isSimilar`, `isUnique`, `isSimpleObject`, `ksort`, `clone`, `UID` undocumented. Also see security review §5 — `merge()` itself needs a doc note about the prototype-pollution caveat once fixed.
- [`src/js/core/functions/server.js`](../src/js/core/functions/server.js) — `encode`/`encodeValue`/`createRequest` (the actual request-building core) undocumented; also has a real bug (implicit globals `data`/`m` in `extractLink()`, security review §15) worth fixing in the same pass.
- [`src/js/core/functions/path.js`](../src/js/core/functions/path.js) — `escape`/`unescape`/`split`/`join`/`lastKey`/`dirname`/`equal` undocumented (used pervasively by `Map`/`Entity`/`Schema` path resolution — worth getting right).
- [`src/js/core/Date.js`](../src/js/core/Date.js) — `compare`, `diff`, `modify`, `get`, `hasTime` undocumented; the module also monkey-patches native `Date.prototype` methods on Firefox at load time (a global side effect) with only an inline comment — deserves a clear top-of-file warning.
- [`src/js/core/history.js`](../src/js/core/history.js) — `Action` subclasses and `Manager` undocumented. Also appears currently dormant (`MMO.history` global instance is commented out in `mmo.js`) — worth a note on whether this module is still maintained or should be removed.
- [`src/js/core/HTMLSearch.js`](../src/js/core/HTMLSearch.js) — `score`, `highlight`, `update` (the actual matching/highlighting logic) undocumented.
- [`src/js/core/Window.js`](../src/js/core/Window.js) — `run`, `onGoto`, `onResize`, `onError` (the rAF-batched run-queue and event-normalization core) undocumented.
- [`src/js/core/Color.js`](../src/js/core/Color.js) — instance methods (`hex`, `name`, `luminance`, `textColor`) undocumented; static factories are fine.
- [`src/js/core/functions/strings.js`](../src/js/core/functions/strings.js) — `bytesize`, `toCamelCase`, `escapeHTML`, `toBoolean`, `printf` under-documented despite `printf` being the interpolation mechanism used throughout error messages.
- [`src/js/schemas/Schema.js`](../src/js/schemas/Schema.js) — the large `test_*` validator methods and computed getters (`type`, `properties`, `getValidTypes`) are undocumented (acceptable if JSON-Schema-familiar, but the file is large enough to benefit from a short per-keyword comment).
- [`src/js/schemas/schemas.js`](../src/js/schemas/schemas.js) — `register`/`unregister`/`exists`/`getById`/`typeof` undocumented.
- [`src/js/elements/Entity.js`](../src/js/elements/Entity.js) — `hasId`, `isEmbedded`, `setLink`, `patch`, the status predicates, and `clone()` undocumented (the harder, less-obvious methods like `save()`/`edit()`/`api()` are documented well).
- [`src/js/core/Map.js`](../src/js/core/Map.js) — the class overall has good top-level and per-method docs, but the trickiest internals (`setExtendedEntries`, `onChildConnection`, `connectWatch`/`disconnectWatch`, `changeWatchPath`, `extendedEntries`) are under-documented relative to their complexity, and the public method `ketAtIndex` has a naming typo (should read `keyAtIndex`) that should be fixed or at least called out. This is the framework's most central reactive-data class — worth a documentation pass on its own, independent of this report.
## Priority 3 — Sass: almost the entire `classes/` and `styles/` directories
Contrast with `_config.scss`/`_functions.scss` (rated **good** — thorough `///` docblocks) and `_default_config.scss`/theme files (rated **partial**, missing an explanation of how the `const` scale multiplies against `sizes` base values, and how `color-scheme`/dark-mode actually connects theme config to runtime).
**Rated `none`** (zero explanatory comments beyond `// ===` section dividers):
- `src/sass/classes/_buttons.scss`, `_colors.scss`, `_customs.scss`, `_inputs.scss`, `_lists.scss`, `_status.scss`, `_tables.scss` — the entire shared `%placeholder` utility-pattern library (buttons, inputs, lists/trees, status badges, tables) has no comments explaining what each placeholder is for or where it's meant to be `@extend`ed from. Right now this has to be reverse-engineered from the `.jhs` files that use it.
- `src/sass/styles/*.scss` (15 of 17 files) — only `_documentation.scss` and part of `_basic.scss` (the device-detection trick) have real comments; the rest (`_buttons`, `_cerfa`, `_colors`, `_components`, `_customs`, `_dump`, `_flex`, `_forms`, `_inputs`, `_lists`, `_logs`, `_medias`, `_prints`, `_status`, `_tables`) rely entirely on selector names for self-explanation.
- `src/sass/styles.scss` — no explanation of import order significance, or which modules are generic vs. domain-specific (`_cerfa.scss` is a French-administrative-form layout, `_documentation.scss` is for the framework's own demo pages — neither is generic, and nothing states that).
**Rated `partial`:**
- `src/sass/_default_config.scss` — token values are all there, but nothing explains the `const` (scale multiplier) vs. `sizes` (base value) relationship, which every size/spacing mixin in `_theme.scss` depends on.
- `src/sass/themes/_default.scss` / `_dark.scss` — good inline comments on non-obvious bits (the `fonts` map format), but no top-level docblock describing the overall theme-map shape, and no pointer to where `color-scheme`/dark-mode toggling is actually wired up at runtime (that logic lives in `mmo-app.jhs`, not in Sass).
**Recommendation:** a single documentation pass over `src/sass/classes/*.scss` would have the highest value-per-hour here, since every `.jhs` custom element's `