Let a desktop theme recommend OS settings

[AllTerrainDeveloper]

Adds an optional recommendedOsSettings block to the desktop-theme manifest, so a theme's intended arrangement travels with it instead of living in a setup guide.

{
  "manifestVersion": 2,
  "recommendedOsSettings": {
    "dockSize": "large",
    "desktopLayout": "unified"
  }
}

The contract: applied once, the first time a user activates the theme — never on page load, never over a change the user made afterwards. A per-user ledger (appliedThemeRecommendations) records which themes have been seeded, so re-picking a theme you've already worn changes nothing. OS Settings → Themes gains an Apply recommended layout button — the only path that applies a recommendation a second time.

Allow-list. Four presentation keys only (dockSize, desktopLayout, windowRadius, dockRailRenderer), filterable via desktop_mode_desktop_theme_recommended_os_settings_schema. The enums reference the existing DESKTOP_MODE_OS_SETTINGS_* constants so they can't drift. dockRailRenderer is checked twice — charset in PHP, registry membership in the shell at apply time — so an id nothing answers to is skipped rather than written into user meta. The shell only writes a key that already exists and already holds a string, so a manifest can't introduce a setting or flip a feature toggle.

Back-compat. manifestVersion now accepts 1 or 2. v1 manifests sanitize exactly as before, and a v1 manifest carrying the block still has it honoured — dropping a valid, sanitized field over a version number would contradict the drop-and-continue rule the rest of the sanitizer follows. Themes installed before this feature shape to an empty set, not a missing key.

Also in here (flagged separately, kept in this PR by request): updateOsSettings had no writer for desktopTheme or unfocusEffect despite the docs showing them, and no windowRadius on the snapshot at all. All three are wired up, and presentation patches now run the apply pass — previously they persisted but changed nothing until the next page load, which is why the docs had to pair updateOsSettings({ desktopTheme }) with a setActive() call.

Docs updated in the same change: desktop-themes.md, hooks-reference.md, javascript-reference.md, api-index.md, examples/register-desktop-theme.md.

Testing

• PHPUnit 1640 passing — new desktopThemesRecommendedOsSettings.php (schema, sanitizer, manifest integration, v1 back-compat, code registration, payload re-sanitization), plus ledger cases and a v2-accepted case.
• Vitest 2400 passing — new desktop-themes-recommended.test.ts and api-update-os-settings.test.ts.
• typecheck, lint, build clean.

Manual: activate a theme with the block → dock/layout move once, with a notice. Change the dock size, re-pick the theme → your choice holds. Hit Apply recommended layout → the author's arrangement comes back. The reference neon-glass theme ZIP ships the block and its README explains the once-only contract.

Theme:
neon-glass.zip