← All changes | includes/os-settings.php +582 -103 0.9.6 → 1.1.10 View file →

		@@ -1,7 +1,7 @@
1	1	<?php
2	2	/**
3		- * Desktop Mode — OS Settings Persistence.
	3	+ * OpenStation — OS Settings Persistence.
4	4	*
5	5	* Persists each user's OS Settings preferences (wallpaper, accent color,
6	6	* dock size, custom gradient/image, HD-only toggle, and AI integration
7	7	* settings) to user meta so they survive across browsers, devices, and
		@@ -8,40 +8,159 @@
8	8	* private/incognito sessions. The JS layer writes to localStorage on
9	9	* every change for instant read-back, then asynchronously syncs to this
10	10	* endpoint so user meta is the durable source of truth.
11	11	*
12		- * @package WPDesktopMode
	12	+ * @package OpenStation
13	13	*/
14	14
15	15	defined( 'ABSPATH' ) || exit;
16	16
17		-/** User meta key for OS Settings. */
18		-const DESKTOP_MODE_OS_SETTINGS_META_KEY = 'desktop_mode_os_settings';
	17	+/**
	18	+ * User meta key for OS Settings.
	19	+ *
	20	+ * The VALUE keeps its pre-rebrand spelling on purpose: it is a
	21	+ * persisted or externally-visible identifier, so renaming it would
	22	+ * orphan data already written by live installs (or break a live
	23	+ * URL). The mismatch between this constant's name and its value is
	24	+ * deliberate — it is NOT a half-finished rename.
	25	+ */
	26	+const OPENSTATION_OS_SETTINGS_META_KEY = 'desktop_mode_os_settings';
19	27
20	28	/** Valid dock-size IDs — mirrors the TS `DOCK_SIZES` constant. */
21		-const DESKTOP_MODE_OS_SETTINGS_DOCK_SIZES = array( 'compact', 'default', 'large' );
	29	+const OPENSTATION_OS_SETTINGS_DOCK_SIZES = array( 'compact', 'default', 'large' );
22	30
	31	+/** Valid window-radius IDs — mirrors the TS `WINDOW_RADII` constant. */
	32	+const OPENSTATION_OS_SETTINGS_WINDOW_RADII = array( 'sharp', 'default', 'round' );
	33	+
	34	+/**
	35	+ * Valid admin-bar mode IDs — mirrors the TS `ADMIN_BAR_MODES` constant.
	36	+ *
	37	+ * `static` keeps the WordPress admin bar pinned above the shell (the
	38	+ * default), `dynamic` auto-hides it to a peek strip that reveals on
	39	+ * hover or keyboard focus, and `hidden` removes it entirely.
	40	+ */
	41	+const OPENSTATION_OS_SETTINGS_ADMIN_BAR_MODES = array( 'static', 'dynamic', 'hidden' );
	42	+
23	43	/** Valid desktop-layout IDs — mirrors the TS `DESKTOP_LAYOUTS` constant. */
24		-const DESKTOP_MODE_OS_SETTINGS_DESKTOP_LAYOUTS = array( 'classic', 'unified', 'spatial' );
	44	+const OPENSTATION_OS_SETTINGS_DESKTOP_LAYOUTS = array( 'classic', 'unified' );
25	45
26	46	/**
	47	+ * Valid dock-placement IDs — mirrors the TS `DOCK_PLACEMENTS` constant.
	48	+ *
	49	+ * Which edge the single dock sits on. Read by the layout dispatcher for
	50	+ * `unified`; `classic` derives its two rails from the layout itself and
	51	+ * ignores this.
	52	+ */
	53	+const OPENSTATION_OS_SETTINGS_DOCK_PLACEMENTS = array( 'bottom', 'left', 'right' );
	54	+
	55	+/**
	56	+ * Valid dock-behavior IDs — mirrors the TS `DOCK_BEHAVIORS` constant.
	57	+ *
	58	+ * `static` keeps the dock always on screen (the default); `dynamic`
	59	+ * parks it off its edge behind a peek strip that reveals when the
	60	+ * pointer reaches that edge or something on it takes keyboard focus,
	61	+ * and releases the band it floats over from the work area.
	62	+ */
	63	+const OPENSTATION_OS_SETTINGS_DOCK_BEHAVIORS = array( 'static', 'dynamic' );
	64	+
	65	+/**
	66	+ * `mobileLayout` — which experience the shell renders. `auto`
	67	+ * follows the viewport; the other two force it either way.
	68	+ * Mirrors `OsModePreference` in `src/mode/index.ts`.
	69	+ */
	70	+const OPENSTATION_OS_SETTINGS_MOBILE_LAYOUTS = array( 'auto', 'desktop', 'mobile' );
	71	+
	72	+/** `mobileTabs` — at most this many ids pinned to the phone tab bar. */
	73	+const OPENSTATION_OS_SETTINGS_MOBILE_TABS_MAX = 3;
	74	+
	75	+/**
	76	+ * Playable range for the window-reveal duration override, in ms.
	77	+ * Mirrors `MIN_REVEAL_DURATION_MS` / `MAX_REVEAL_DURATION_MS` in
	78	+ * `src/reveals/registry.ts`.
	79	+ *
	80	+ * `0` sits OUTSIDE this range on purpose: it is the "no override"
	81	+ * sentinel, not a duration, and is handled before the clamp.
	82	+ */
	83	+const OPENSTATION_OS_SETTINGS_REVEAL_DURATION_MIN = 80;
	84	+const OPENSTATION_OS_SETTINGS_REVEAL_DURATION_MAX = 4000;
	85	+
	86	+/**
27	87	* Returns a well-shaped default OS settings array.
28	88	*
29	89	* Mirrors the TypeScript `DEFAULTS` constant so a fresh user account
30	90	* gets the same starting state in both environments.
31	91	*
32		- * @since 0.5.0
33		- *
34	92	* @return array
35	93	*/
36		-function desktop_mode_default_os_settings() {
	94	+function openstation_default_os_settings() {
37	95	return array(
38		- 'wallpaper' => 'dark',
39		- 'accent' => 'wp-blue',
	96	+ 'wallpaper' => 'galaxy',
	97	+ // Pulse, the brand's signature. Mirrors `DEFAULTS` in
	98	+ // `src/settings/constants.ts`.
	99	+ 'accent' => 'pulse',
	100	+ // Only read when `accent` is `custom`. Seeded with Pulse so
	101	+ // picking Custom before touching the wheel is a no-op rather
	102	+ // than a jump to black. Mirrors `DEFAULTS` in
	103	+ // `src/settings/constants.ts`.
	104	+ 'customAccent' => '#f252fc',
40	105	'dockSize' => 'default',
41		- 'desktopLayout' => 'classic',
	106	+ // `round` (16px), not the preset id literally named `default`.
	107	+ // Preset ids are stored values and cannot be renamed, so the
	108	+ // option labelled "Default" in the picker is no longer the
	109	+ // shipped default. Must stay in step with `DEFAULTS` in
	110	+ // `src/settings/constants.ts` — PHP seeds the first load and JS
	111	+ // owns every paint after it, so a mismatch shows up as the
	112	+ // corners changing shape a moment after the shell boots.
	113	+ 'windowRadius' => 'round',
	114	+ // How the WordPress admin bar presents above the shell.
	115	+ // `hidden` ships as the default so a fresh desktop has ONE
	116	+ // navigation surface: everything the user can open lives on the
	117	+ // dock, and the dock's "Exit OpenStation" tile is the way back
	118	+ // to classic admin. `static` (vanilla behavior) and `dynamic`
	119	+ // are one pick away in OpenStation Preferences → Appearance.
	120	+ 'adminBarMode' => 'hidden',
	121	+ // Always on screen. `dynamic` (auto-hide behind a peek strip)
	122	+ // is one pick away in OpenStation Preferences → Appearance.
	123	+ 'dockBehavior' => 'static',
	124	+ // The Split layout's sidebar answers for itself: a folded
	125	+ // sidebar over a static bottom dock is a valid desk.
	126	+ 'sideDockBehavior' => 'static',
	127	+ // One dock holding every menu, with the system tiles grouped
	128	+ // behind a hairline. `classic` (side bar for core menus + bottom
	129	+ // dock for plugins) is the other option; it is no longer what a
	130	+ // first-run desktop looks like.
	131	+ 'desktopLayout' => 'unified',
	132	+ // Which edge the single dock sits on. Ignored by `classic`,
	133	+ // which derives both of its rails from the layout.
	134	+ 'dockPlacement' => 'bottom',
42	135	'dockRailRenderer' => 'default',
	136	+ // Active desktop-theme slug, or `''` for the system default.
	137	+ // Site-wide library (`includes/desktop-themes/`), per-user
	138	+ // activation. Not validated against the installed list here —
	139	+ // the enqueue path checks existence on every request, so a
	140	+ // deleted theme degrades silently instead of needing a
	141	+ // user-meta rewrite.
	142	+ 'desktopTheme' => '',
	143	+ // Slugs of the desktop themes whose `recommendedOsSettings`
	144	+ // block has already been applied for this user. A theme's
	145	+ // recommendations are seeded ONCE — the first time the user
	146	+ // activates it — and this list is the record of that. It is
	147	+ // what makes "never overwrite a user's later choices" true:
	148	+ // re-activating a theme they have worn before changes
	149	+ // nothing. The Themes tab's "Apply recommended layout" action
	150	+ // is the deliberate way back. Capped at 64 slugs.
	151	+ 'appliedThemeRecommendations' => array(),
43	152	'unfocusEffect' => 'darken',
	153	+ // Window-reveal id — the clip-path transition that uncovers a
	154	+ // window's content once it finishes loading. Off by default;
	155	+ // `none` is the plain opacity fade the shell has always had.
	156	+ 'windowReveal' => 'none',
	157	+ // Global reveal duration override in ms. 0 means "use each
	158	+ // reveal's own tuned timing" — the shipped reveals have
	159	+ // durations chosen per shape (Radar's full turn is slower
	160	+ // than Sweep's straight line), and one flat number would
	161	+ // lose that.
	162	+ 'windowRevealDuration' => 0,
44	163	// Window-link renderer id — how relation ties between windows
45	164	// are drawn (see includes/window-links.php). `svg-splines` is
46	165	// the shipped built-in; `none` disables the visuals.
47	166	'windowLinkRenderer' => 'svg-splines',
		@@ -75,11 +194,11 @@
75	194	'ai' => array(
76	195	'enabled' => false, // AI assistant is opt-in; enabled from OS Settings → Features once a provider is configured.
77	196	),
78	197	// Per-user opt-IN for the native Posts window. When true,
79		- // clicking the Posts dock tile opens the `<wpd-table>`-driven
	198	+ // clicking the Posts dock tile opens the `<os-table>`-driven
80	199	// native window instead of the chromeless `edit.php` iframe.
81		- // Default OFF as of 0.9.1 — the native windows are now opt-in
	200	+ // Default OFF — the native windows are opt-in
82	201	// Beta. Fresh installs land on the classic iframe; users turn
83	202	// this on in OS Settings → Features → Beta features to try it.
84	203	// Per-user override of the WordPress Heartbeat interval, in
85	204	// seconds. 60s matches Core's "idle" default; the allowed
		@@ -84,9 +203,9 @@
84	203	// Per-user override of the WordPress Heartbeat interval, in
85	204	// seconds. 60s matches Core's "idle" default; the allowed
86	205	// rates (15/30/45/60) all sit at or above Core's 15 s
87	206	// `minimalInterval` floor. See
88		- // `desktop_mode_apply_heartbeat_rate_setting` for the
	207	+ // `openstation_apply_heartbeat_rate_setting` for the
89	208	// `heartbeat_settings` filter that applies this.
90	209	'heartbeatRate' => 60,
91	210	'nativePostsEnabled' => false,
92	211	// Per-user list of column keys hidden in the native Posts
		@@ -93,8 +212,13 @@
93	212	// window (e.g. array( 'author', 'tags' )). Empty array means
94	213	// every column is visible. The sticky 'title' column is always
95	214	// shown — the UI prevents toggling it.
96	215	'nativePostsHiddenColumns' => array(),
	216	+ // Per-user list of column keys hidden in the native Pages
	217	+ // window (e.g. array( 'author', 'parent' )). Empty array means
	218	+ // every column is visible. The sticky 'title' column is always
	219	+ // shown — the UI prevents toggling it.
	220	+ 'nativePagesHiddenColumns' => array(),
97	221	// Per-user opt-IN for the native Pages window. Same posture as
98	222	// nativePostsEnabled — defaults OFF (Beta), users opt in to swap
99	223	// the classic `edit.php?post_type=page` iframe for the native UI.
100	224	'nativePagesEnabled' => false,
		@@ -111,8 +235,17 @@
111	235	// Per-user opt-IN for the native Comments window. Defaults OFF
112	236	// (Beta); the server-side cap gate (`edit_posts`) means the
113	237	// toggle only matters for users who could see the Comments tile.
114	238	'nativeCommentsEnabled' => false,
	239	+ // Per-user opt-IN for Station Home, the native Dashboard
	240	+ // window. Defaults OFF: the ordinary `index.php` Dashboard
	241	+ // (including any custom dashboard a plugin builds there) opens
	242	+ // as a chromeless iframe until the user opts in via OS
	243	+ // Settings → Features → Beta features.
	244	+ 'stationHomeEnabled' => false,
	245	+ // Performance enhancements are enabled unless explicitly disabled.
	246	+ 'adminAssetCacheEnabled' => true,
	247	+ 'windowPrewarmEnabled' => true,
115	248	// When true, left-clicking the empty wallpaper triggers the
116	249	// "Show desktop" toggle (macOS-style) and the matching entry is
117	250	// hidden from the wallpaper context menu. When false (default),
118	251	// the entry stays in the menu and left clicks on the wallpaper
		@@ -117,8 +250,31 @@
117	250	// hidden from the wallpaper context menu. When false (default),
118	251	// the entry stays in the menu and left clicks on the wallpaper
119	252	// do nothing. Per-user.
120	253	'showDesktopOnWallpaperClick' => false,
	254	+ // Whether the close-all-windows shortcut (Alt+Cmd/Ctrl+W) asks
	255	+ // before it closes. The dialog's "Don't ask again" checkbox is
	256	+ // what writes false; OpenStation Preferences -> Windows is what
	257	+ // turns it back on. Per-user.
	258	+ 'confirmCloseAllWindows' => true,
	259	+ // Mio — a soft-body companion that floats over
	260	+ // the wallpaper, settles onto nearby windows, and watches the
	261	+ // pointer. Off by default; toggled from the wallpaper context
	262	+ // menu. Per-user. See `docs/mio.md`.
	263	+ 'mioEnabled' => false,
	264	+ 'mioApiEnabled' => false,
	265	+ 'mioShowOnWallpaper' => true,
	266	+ // The user's own Mio, as built in "Make it yours": partial
	267	+ // appearance + silhouette overrides, both empty until they
	268	+ // touch a control. Stored per user rather than per browser
	269	+ // because it is a preference about the person — ten minutes
	270	+ // spent building a companion should be waiting on their phone.
	271	+ // Sanitized by `openstation_sanitize_mio_look()`; the ranges
	272	+ // are enforced client-side in `sanitizeMioConfig()`.
	273	+ 'mioStyle' => array(
	274	+ 'appearance' => array(),
	275	+ 'physics' => array(),
	276	+ ),
121	277	// Diagonal corner ribbon on My WordPress tiles whose post
122	278	// status isn't `publish` (draft / pending / private /
123	279	// scheduled). On by default — surfaces unpublished work at
124	280	// a glance. Per-user.
		@@ -124,11 +280,12 @@
124	280	// a glance. Per-user.
125	281	'showPostStatusRibbons' => true,
126	282	// Unlocks developer-facing surfaces meant for plugin
127	283	// authors: the Starter Widget appears in the add-widget
128		- // picker, and the OS Settings → Components tab runs its
129		- // intentional missing-import-warner demo. Off by default.
130		- // Per-user.
	284	+ // picker, the OS Settings → Components tab runs its
	285	+ // intentional missing-import-warner demo, and the Code Blue
	286	+ // error-log reader registers (icon, window, REST routes).
	287	+ // Off by default. Per-user.
131	288	'developerModeEnabled' => false,
132	289	// Per-user opt-OUT for the folder-sharing feature. Defaults
133	290	// ON. When false:
134	291	// - The Share button, share-settings modal, "Leave shared
		@@ -143,23 +300,30 @@
143	300	// disappears without any database changes. The site-wide
144	301	// "Delete folder sharing data" action in OS Settings →
145	302	// Features → Advanced is a separate destructive cleanup.
146	303	'foldersSharingEnabled' => true,
147		- // Per-item placement preferences. Map of item id (dock-item
148		- // slug or registered desktop-icon id) → one of:
149		- // 'both' — show on both dock and desktop.
150		- // 'dock' — show only on the dock; hide from desktop.
151		- // 'desktop' — show only on the wallpaper; hide from dock.
	304	+ // Per-item navigation placement. Map of item id → one of:
	305	+ // 'both' — show on a rail and on the desktop.
	306	+ // 'rail' — show only on a rail: the dock, or the sidebar
	307	+ // for a Core admin menu in the split layout.
	308	+ // 'desktop' — show only on the wallpaper.
152	309	// 'hidden' — hide from every shell surface.
153		- // Missing keys mean "no override" — items use their native rail.
	310	+ // Missing keys mean "no override" — the item takes the default
	311	+ // for its kind, which lives in `src/nav/defaults.ts`.
154	312	// Sanitized as map<sanitize_key, enum>. Capped at 256 entries.
155		- 'itemVisibility' => array(),
156		- // Per-user dock ordering. Ordered list of item ids; ids not in
157		- // the list keep their server-supplied position appended after
158		- // the listed ones. Unknown ids are tolerated.
159		- 'dockOrder' => array(),
160		- // Persisted desktop position for every dock item the user has
161		- // promoted to the wallpaper via `itemVisibility[id]=desktop|both`.
	313	+ 'navPlacement' => array(),
	314	+ // Per-user ordering, flat across every dock/sidebar zone. Ids
	315	+ // not in the list keep their registration order and render
	316	+ // after the listed ones. Unknown ids are tolerated.
	317	+ 'navOrder' => array(),
	318	+ // Which experience the shell renders: 'auto' follows the
	319	+ // viewport, 'desktop' / 'mobile' force it. See `includes/mobile.php`.
	320	+ 'mobileLayout' => 'auto',
	321	+ // Ids pinned to the phone tab bar, at most three. Empty means
	322	+ // the server default (`openstation_mobile_tab_bar`).
	323	+ 'mobileTabs' => array(),
	324	+ // Persisted desktop position for every item the user has
	325	+ // promoted to the wallpaper via `navPlacement[id]=desktop|both`.
162	326	// Keyed by item id, value is `{ x: int, y: int }`. The JS
163	327	// synthesizer reads this when building a synthetic placement so
164	328	// the icon lands where the user last dragged it instead of
165	329	// resetting to (0, 0) on every reload. Capped at 256 entries.
		@@ -172,47 +336,111 @@
172	336	*
173	337	* Always returns a fully-shaped array so the JS side doesn't need to
174	338	* defend against partial or missing keys.
175	339	*
176		- * @since 0.5.0
177		- *
178	340	* @param int $user_id The user ID.
179	341	* @return array
180	342	*/
181		-function desktop_mode_get_os_settings( $user_id ) {
	343	+function openstation_get_os_settings( $user_id ) {
182	344	$user_id = (int) $user_id;
183	345	if ( $user_id <= 0 ) {
184		- return desktop_mode_default_os_settings();
	346	+ return openstation_sanitize_os_settings( array() );
185	347	}
186	348
187		- $raw = get_user_meta( $user_id, DESKTOP_MODE_OS_SETTINGS_META_KEY, true );
	349	+ $raw = get_user_meta( $user_id, OPENSTATION_OS_SETTINGS_META_KEY, true );
188	350	if ( ! is_array( $raw ) ) {
189		- return desktop_mode_default_os_settings();
	351	+ return openstation_sanitize_os_settings( array() );
190	352	}
191	353
192		- return desktop_mode_sanitize_os_settings( $raw );
	354	+ return openstation_sanitize_os_settings( $raw );
193	355	}
194	356
195	357	/**
196	358	* Saves sanitized OS settings for a user.
197	359	*
198		- * @since 0.5.0
199		- *
200	360	* @param int $user_id The user ID.
201	361	* @param mixed $settings Raw settings payload from the client.
202	362	* @return bool True on success, false otherwise.
203	363	*/
204		-function desktop_mode_save_os_settings( $user_id, $settings ) {
	364	+function openstation_save_os_settings( $user_id, $settings ) {
205	365	$user_id = (int) $user_id;
206	366	if ( $user_id <= 0 ) {
207	367	return false;
208	368	}
209	369
210		- $clean = desktop_mode_sanitize_os_settings( $settings );
211		- return false !== update_user_meta( $user_id, DESKTOP_MODE_OS_SETTINGS_META_KEY, $clean );
	370	+ $clean = openstation_sanitize_os_settings( $settings );
	371	+ return false !== update_user_meta( $user_id, OPENSTATION_OS_SETTINGS_META_KEY, $clean );
212	372	}
213	373
214	374	/**
	375	+ * Strip the rail-synthesis prefix an id could carry before the
	376	+ * navigation model.
	377	+ *
	378	+ * `dock:<id>` / `desktop:<id>` used to mean "this tile is a copy of an
	379	+ * item whose real home is the other rail". Nothing synthesizes copies
	380	+ * any more — an item is one item wherever it is painted — so the
	381	+ * prefix is noise, and left in place it would key a preference to an
	382	+ * id nothing registers.
	383	+ *
	384	+ * @param string $id Possibly-prefixed id.
	385	+ * @return string Canonical id.
	386	+ */
	387	+function openstation_canonical_nav_id( $id ) {
	388	+ $id = (string) $id;
	389	+ if ( 0 === strpos( $id, 'dock:' ) ) {
	390	+ return substr( $id, 5 );
	391	+ }
	392	+ if ( 0 === strpos( $id, 'desktop:' ) ) {
	393	+ return substr( $id, 8 );
	394	+ }
	395	+ return $id;
	396	+}
	397	+
	398	+/**
	399	+ * Carry a pre-navigation `itemVisibility` map into `navPlacement`.
	400	+ *
	401	+ * The only value that moves is `'dock'` → `'rail'`: the stored name
	402	+ * is now the REGION rather than a rail, so a Core admin menu the user
	403	+ * kept on a rail follows the layout into the sidebar instead of
	404	+ * needing a second migration the first time they switch.
	405	+ *
	406	+ * Runs on read (see {@see openstation_sanitize_os_settings()}) rather
	407	+ * than as a numbered migration, because OS settings are per-user meta
	408	+ * and a site with many users would pay for a sweep that the next save
	409	+ * performs for free.
	410	+ *
	411	+ * @param array $visibility Legacy map of item id → placement.
	412	+ * @return array Map of canonical item id → nav placement.
	413	+ */
	414	+function openstation_migrate_item_visibility( $visibility ) {
	415	+ $map = array(
	416	+ 'dock' => 'rail',
	417	+ 'desktop' => 'desktop',
	418	+ 'both' => 'both',
	419	+ 'hidden' => 'hidden',
	420	+ );
	421	+
	422	+ $out = array();
	423	+ foreach ( (array) $visibility as $key => $val ) {
	424	+ if ( ! is_string( $key ) || ! is_string( $val ) || ! isset( $map[ $val ] ) ) {
	425	+ continue;
	426	+ }
	427	+ $id = openstation_canonical_nav_id( $key );
	428	+ if ( '' === $id ) {
	429	+ continue;
	430	+ }
	431	+ // A prefixed and an unprefixed key can collapse onto the same
	432	+ // id. The unprefixed one is the item's own preference rather
	433	+ // than a synthesized copy's, so it wins whichever order they
	434	+ // arrive in.
	435	+ if ( $id === $key || ! isset( $out[ $id ] ) ) {
	436	+ $out[ $id ] = $map[ $val ];
	437	+ }
	438	+ }
	439	+ return $out;
	440	+}
	441	+
	442	+/**
215	443	* Sanitizes a raw OS settings payload.
216	444	*
217	445	* Unknown keys are ignored; known keys are coerced field-by-field so a
218	446	* partial save (e.g., only accent changed) merges cleanly with the
		@@ -217,18 +445,16 @@
217	445	* Unknown keys are ignored; known keys are coerced field-by-field so a
218	446	* partial save (e.g., only accent changed) merges cleanly with the
219	447	* defaults rather than wiping unset fields.
220	448	*
221		- * @since 0.5.0
222		- *
223	449	* @param mixed $raw Raw settings from the client or user meta.
224	450	* @return array Sanitized settings.
225	451	*/
226		-function desktop_mode_sanitize_os_settings( $raw ) {
227		- $defaults = desktop_mode_default_os_settings();
	452	+function openstation_sanitize_os_settings( $raw ) {
	453	+ $defaults = openstation_default_os_settings();
228	454
229	455	if ( ! is_array( $raw ) ) {
230		- return $defaults;
	456	+ $raw = array();
231	457	}
232	458
233	459	// Wallpaper — any non-empty string; registry membership is validated
234	460	// client-side at apply time.
		@@ -240,20 +466,59 @@
240	466	$accent = isset( $raw['accent'] ) && is_string( $raw['accent'] ) && '' !== $raw['accent']
241	467	? sanitize_key( $raw['accent'] )
242	468	: $defaults['accent'];
243	469
	470	+ // The colour behind the Custom swatch. A full `#rrggbb` triplet and
	471	+ // nothing else: `sanitize_hex_color()` would also pass `#abc`, which
	472	+ // the client-side parser rejects, and a value that survives the save
	473	+ // only to be dropped on load is worse than one refused here.
	474	+ $custom_accent = isset( $raw['customAccent'] )
	475	+ && is_string( $raw['customAccent'] )
	476	+ && preg_match( '/^#[0-9a-fA-F]{6}$/', $raw['customAccent'] )
	477	+ ? strtolower( $raw['customAccent'] )
	478	+ : $defaults['customAccent'];
	479	+
244	480	// Dock size — must be one of the three known values.
245		- $dock_size = isset( $raw['dockSize'] ) && in_array( $raw['dockSize'], DESKTOP_MODE_OS_SETTINGS_DOCK_SIZES, true )
	481	+ $dock_size = isset( $raw['dockSize'] ) && in_array( $raw['dockSize'], OPENSTATION_OS_SETTINGS_DOCK_SIZES, true )
246	482	? (string) $raw['dockSize']
247	483	: $defaults['dockSize'];
248	484
249		- // Desktop layout — must be one of the three known values
250		- // (`classic`, `unified`, `spatial`). Default `classic`.
	485	+ // Window radius — must be one of the three known values.
	486	+ $window_radius = isset( $raw['windowRadius'] ) && in_array( $raw['windowRadius'], OPENSTATION_OS_SETTINGS_WINDOW_RADII, true )
	487	+ ? (string) $raw['windowRadius']
	488	+ : $defaults['windowRadius'];
	489	+
	490	+ // Admin-bar mode — must be one of the three known values.
	491	+ $admin_bar_mode = isset( $raw['adminBarMode'] )
	492	+ && in_array( $raw['adminBarMode'], OPENSTATION_OS_SETTINGS_ADMIN_BAR_MODES, true )
	493	+ ? (string) $raw['adminBarMode']
	494	+ : $defaults['adminBarMode'];
	495	+
	496	+ // Dock behavior — must be one of the two known values. One answer
	497	+ // per rail: the dock, and the Split layout's sidebar.
	498	+ $dock_behavior = isset( $raw['dockBehavior'] )
	499	+ && in_array( $raw['dockBehavior'], OPENSTATION_OS_SETTINGS_DOCK_BEHAVIORS, true )
	500	+ ? (string) $raw['dockBehavior']
	501	+ : $defaults['dockBehavior'];
	502	+ $side_dock_behavior = isset( $raw['sideDockBehavior'] )
	503	+ && in_array( $raw['sideDockBehavior'], OPENSTATION_OS_SETTINGS_DOCK_BEHAVIORS, true )
	504	+ ? (string) $raw['sideDockBehavior']
	505	+ : $defaults['sideDockBehavior'];
	506	+
	507	+ // Desktop layout — must be one of the known values (`classic`,
	508	+ // `unified`). Default `unified`.
251	509	$desktop_layout = isset( $raw['desktopLayout'] )
252		- && in_array( $raw['desktopLayout'], DESKTOP_MODE_OS_SETTINGS_DESKTOP_LAYOUTS, true )
	510	+ && in_array( $raw['desktopLayout'], OPENSTATION_OS_SETTINGS_DESKTOP_LAYOUTS, true )
253	511	? (string) $raw['desktopLayout']
254	512	: $defaults['desktopLayout'];
255	513
	514	+ // Dock placement — which edge the single dock sits on. Must be one
	515	+ // of the three known values (`bottom`, `left`, `right`).
	516	+ $dock_placement = isset( $raw['dockPlacement'] )
	517	+ && in_array( $raw['dockPlacement'], OPENSTATION_OS_SETTINGS_DOCK_PLACEMENTS, true )
	518	+ ? (string) $raw['dockPlacement']
	519	+ : $defaults['dockPlacement'];
	520	+
256	521	// Dock rail renderer id — accept any sanitize_key()-clean
257	522	// string. JS-side registry resolves at use time and falls back
258	523	// to `'default'` when the picked renderer isn't registered.
259	524	$dock_rail_renderer = $defaults['dockRailRenderer'];
		@@ -263,8 +528,46 @@
263	528	$dock_rail_renderer = $slug;
264	529	}
265	530	}
266	531
	532	+ // Desktop theme slug — a pattern check, NOT an allow-list, the
	533	+ // same idiom as `dockRailRenderer` above. Validating against the
	534	+ // installed-theme option here would load (and unserialize) that
	535	+ // option on every single settings write for a value the enqueue
	536	+ // path re-checks anyway. `''` is the system default and is a
	537	+ // legitimate value, so an empty/absent key keeps the default.
	538	+ $desktop_theme = $defaults['desktopTheme'];
	539	+ if ( isset( $raw['desktopTheme'] ) && is_string( $raw['desktopTheme'] ) ) {
	540	+ $desktop_theme = sanitize_key( $raw['desktopTheme'] );
	541	+ }
	542	+
	543	+ // appliedThemeRecommendations — list of desktop-theme slugs whose
	544	+ // recommendations this user has already been seeded with. Unknown
	545	+ // slugs are kept (a deleted-then-reinstalled theme must not
	546	+ // re-seed and clobber the settings the user has since chosen).
	547	+ $applied_theme_recommendations = $defaults['appliedThemeRecommendations'];
	548	+ if ( isset( $raw['appliedThemeRecommendations'] ) && is_array( $raw['appliedThemeRecommendations'] ) ) {
	549	+ $applied_theme_recommendations = array();
	550	+ foreach ( $raw['appliedThemeRecommendations'] as $theme_slug ) {
	551	+ if ( ! is_string( $theme_slug ) || '' === $theme_slug ) {
	552	+ continue;
	553	+ }
	554	+ $theme_slug = sanitize_key( $theme_slug );
	555	+ if ( '' === $theme_slug ) {
	556	+ continue;
	557	+ }
	558	+ $applied_theme_recommendations[] = $theme_slug;
	559	+ }
	560	+ // Keep the MOST RECENT 64, not the first 64 — the client
	561	+ // appends, so trimming from the front would silently discard
	562	+ // the entry that was just written and let the theme re-seed on
	563	+ // the next activation.
	564	+ $applied_theme_recommendations = array_slice(
	565	+ array_values( array_unique( $applied_theme_recommendations ) ),
	566	+ -64
	567	+ );
	568	+ }
	569	+
267	570	// Unfocus effect id — accept the `none` sentinel or any registry id.
268	571	// Effect ids mirror the JS registry pattern `^[a-z0-9_/-]+$` (slashes
269	572	// allowed for `vendor/sub-id` namespacing), so we lower-case and strip
270	573	// to that charset rather than using sanitize_key() (which would drop
		@@ -278,8 +581,39 @@
278	581	$unfocus_effect = $slug;
279	582	}
280	583	}
281	584
	585	+ // Window-reveal id — same id charset and same no-allow-list
	586	+ // reasoning as the unfocus effect above. The JS surface resolves at
	587	+ // play time and treats an unknown id as "no reveal", so a reveal
	588	+ // belonging to a temporarily-deactivated plugin survives the
	589	+ // round-trip and starts working again the moment it re-registers.
	590	+ $window_reveal = $defaults['windowReveal'];
	591	+ if ( isset( $raw['windowReveal'] ) && is_string( $raw['windowReveal'] ) ) {
	592	+ $slug = preg_replace( '/[^a-z0-9_\/-]/', '', strtolower( $raw['windowReveal'] ) );
	593	+ if ( '' !== $slug ) {
	594	+ $window_reveal = $slug;
	595	+ }
	596	+ }
	597	+
	598	+ // Window-reveal duration override — 0 (the default) means "leave
	599	+ // each reveal's own timing alone". Anything else is clamped into
	600	+ // the playable range rather than rejected: a value past the end of
	601	+ // the range still expresses a direction, and the nearest playable
	602	+ // duration is the honest reading of it.
	603	+ $window_reveal_duration = $defaults['windowRevealDuration'];
	604	+ if ( isset( $raw['windowRevealDuration'] ) && is_numeric( $raw['windowRevealDuration'] ) ) {
	605	+ $requested = (int) round( (float) $raw['windowRevealDuration'] );
	606	+ if ( $requested > 0 ) {
	607	+ $window_reveal_duration = max(
	608	+ OPENSTATION_OS_SETTINGS_REVEAL_DURATION_MIN,
	609	+ min( OPENSTATION_OS_SETTINGS_REVEAL_DURATION_MAX, $requested )
	610	+ );
	611	+ } else {
	612	+ $window_reveal_duration = 0;
	613	+ }
	614	+ }
	615	+
282	616	// Window-link renderer id — same id charset as unfocus effects
283	617	// (slashes allowed for `vendor/sub-id`). No allow-list: the JS
284	618	// render host resolves at use time and falls back to the built-in
285	619	// `svg-splines` when the picked renderer isn't registered.
		@@ -412,9 +746,9 @@
412	746	}
413	747	}
414	748
415	749	// Heartbeat rate — one of the four allowed values. The PHP
416		- // filter `desktop_mode_apply_heartbeat_rate_setting` reads
	750	+ // filter `openstation_apply_heartbeat_rate_setting` reads
417	751	// this and passes it through to `heartbeat_settings` so
418	752	// WordPress Core itself reduces the interval on the next page
419	753	// load. 5 s is intentionally excluded: Core's
420	754	// `minimalInterval` floor clamps anything below 15 back up to
		@@ -451,8 +785,27 @@
451	785	// user meta indefinitely.
452	786	$native_posts_hidden_columns = array_slice( array_values( array_unique( $native_posts_hidden_columns ) ), 0, 32 );
453	787	}
454	788
	789	+ $native_pages_hidden_columns = $defaults['nativePagesHiddenColumns'];
	790	+ if ( isset( $raw['nativePagesHiddenColumns'] ) && is_array( $raw['nativePagesHiddenColumns'] ) ) {
	791	+ $native_pages_hidden_columns = array();
	792	+ foreach ( $raw['nativePagesHiddenColumns'] as $col ) {
	793	+ if ( ! is_string( $col ) || '' === $col ) {
	794	+ continue;
	795	+ }
	796	+ $slug = sanitize_key( $col );
	797	+ if ( '' === $slug ) {
	798	+ continue;
	799	+ }
	800	+ $native_pages_hidden_columns[] = $slug;
	801	+ }
	802	+ // Cap to a sane upper bound — far more than any plausible
	803	+ // column count, but blocks a malicious payload from bloating
	804	+ // user meta indefinitely.
	805	+ $native_pages_hidden_columns = array_slice( array_values( array_unique( $native_pages_hidden_columns ) ), 0, 32 );
	806	+ }
	807	+
455	808	$native_pages_enabled = isset( $raw['nativePagesEnabled'] )
456	809	? (bool) $raw['nativePagesEnabled']
457	810	: $defaults['nativePagesEnabled'];
458	811
		@@ -467,12 +820,37 @@
467	820	$native_comments_enabled = isset( $raw['nativeCommentsEnabled'] )
468	821	? (bool) $raw['nativeCommentsEnabled']
469	822	: $defaults['nativeCommentsEnabled'];
470	823
	824	+ $station_home_enabled = isset( $raw['stationHomeEnabled'] )
	825	+ ? (bool) $raw['stationHomeEnabled']
	826	+ : $defaults['stationHomeEnabled'];
	827	+
	828	+ // Site-wide performance controls supersede the legacy per-user values.
	829	+ // Keep the snapshot keys so existing window consumers can read them.
	830	+ $extended_options = openstation_get_extended_options();
	831	+ $admin_asset_cache_enabled = $extended_options['admin_asset_cache'];
	832	+ $window_prewarm_enabled = $extended_options['window_prewarm'];
	833	+
471	834	$show_desktop_on_wallpaper_click = isset( $raw['showDesktopOnWallpaperClick'] )
472	835	? (bool) $raw['showDesktopOnWallpaperClick']
473	836	: $defaults['showDesktopOnWallpaperClick'];
474	837
	838	+ $confirm_close_all_windows = isset( $raw['confirmCloseAllWindows'] )
	839	+ ? (bool) $raw['confirmCloseAllWindows']
	840	+ : $defaults['confirmCloseAllWindows'];
	841	+
	842	+ $mio_enabled = isset( $raw['mioEnabled'] )
	843	+ ? (bool) $raw['mioEnabled']
	844	+ : ( isset( $raw['mioApiEnabled'] ) ? (bool) $raw['mioApiEnabled'] : $defaults['mioEnabled'] );
	845	+
	846	+ // A missing key means "no look saved yet", which sanitizes to the
	847	+ // same pair of empty arrays the defaults carry — so this needs no
	848	+ // isset() branch of its own.
	849	+ $mio_style = openstation_sanitize_mio_look(
	850	+ isset( $raw['mioStyle'] ) ? $raw['mioStyle'] : null
	851	+ );
	852	+
475	853	$show_post_status_ribbons = isset( $raw['showPostStatusRibbons'] )
476	854	? (bool) $raw['showPostStatusRibbons']
477	855	: $defaults['showPostStatusRibbons'];
478	856
		@@ -479,20 +857,59 @@
479	857	$developer_mode_enabled = isset( $raw['developerModeEnabled'] )
480	858	? (bool) $raw['developerModeEnabled']
481	859	: $defaults['developerModeEnabled'];
482	860
	861	+ // mobileLayout — the phone/desktop override.
	862	+ $mobile_layout = isset( $raw['mobileLayout'] )
	863	+ && in_array( $raw['mobileLayout'], OPENSTATION_OS_SETTINGS_MOBILE_LAYOUTS, true )
	864	+ ? (string) $raw['mobileLayout']
	865	+ : $defaults['mobileLayout'];
	866	+
	867	+ // mobileTabs — ordered nav ids pinned to the phone tab bar. Same
	868	+ // id grammar as navOrder, capped at the tab bar's slot count.
	869	+ $mobile_tabs = array();
	870	+ if ( isset( $raw['mobileTabs'] ) && is_array( $raw['mobileTabs'] ) ) {
	871	+ $seen_tabs = array();
	872	+ foreach ( $raw['mobileTabs'] as $id ) {
	873	+ if ( ! is_string( $id ) || '' === $id ) {
	874	+ continue;
	875	+ }
	876	+ $slug = sanitize_key( openstation_canonical_nav_id( $id ) );
	877	+ if ( '' === $slug || isset( $seen_tabs[ $slug ] ) ) {
	878	+ continue;
	879	+ }
	880	+ $seen_tabs[ $slug ] = true;
	881	+ $mobile_tabs[] = $slug;
	882	+ if ( count( $mobile_tabs ) >= OPENSTATION_OS_SETTINGS_MOBILE_TABS_MAX ) {
	883	+ break;
	884	+ }
	885	+ }
	886	+ }
	887	+
483	888	$folders_sharing_enabled = isset( $raw['foldersSharingEnabled'] )
484	889	? (bool) $raw['foldersSharingEnabled']
485	890	: $defaults['foldersSharingEnabled'];
486	891
487		- // itemVisibility — map<sanitize_key, enum>. Unknown ids are kept
	892	+ // navPlacement — map<sanitize_key, enum>. Unknown ids are kept
488	893	// (a deactivated plugin's setting should survive reactivation);
489	894	// invalid placement values are dropped.
490		- $item_visibility = array();
491		- if ( isset( $raw['itemVisibility'] ) && is_array( $raw['itemVisibility'] ) ) {
492		- $allowed_placements = array( 'both', 'dock', 'desktop', 'hidden' );
	895	+ //
	896	+ // Reads the pre-navigation `itemVisibility` map when this user has
	897	+ // no `navPlacement` yet, so an existing arrangement carries over on
	898	+ // first load and is written back on the next save. See
	899	+ // `openstation_migrate_item_visibility()`.
	900	+ $raw_placement = array();
	901	+ if ( isset( $raw['navPlacement'] ) && is_array( $raw['navPlacement'] ) ) {
	902	+ $raw_placement = $raw['navPlacement'];
	903	+ } elseif ( isset( $raw['itemVisibility'] ) && is_array( $raw['itemVisibility'] ) ) {
	904	+ $raw_placement = openstation_migrate_item_visibility( $raw['itemVisibility'] );
	905	+ }
	906	+
	907	+ $nav_placement = array();
	908	+ if ( ! empty( $raw_placement ) ) {
	909	+ $allowed_placements = array( 'both', 'rail', 'desktop', 'hidden' );
493	910	$count = 0;
494		- foreach ( $raw['itemVisibility'] as $key => $val ) {
	911	+ foreach ( $raw_placement as $key => $val ) {
495	912	if ( $count >= 256 ) {
496	913	break;
497	914	}
498	915	if ( ! is_string( $key ) || '' === $key || ! is_string( $val ) ) {
		@@ -504,34 +921,38 @@
504	921	}
505	922	if ( ! in_array( $val, $allowed_placements, true ) ) {
506	923	continue;
507	924	}
508		- $item_visibility[ $slug ] = $val;
	925	+ $nav_placement[ $slug ] = $val;
509	926	++$count;
510	927	}
511	928	}
512	929
513		- // dockOrder — ordered list of item ids. Most are sanitize_key()-
514		- // clean dock slugs, but cross-rail tiles the user promoted carry a
515		- // rail-synthesis prefix (`desktop:<id>` / `dock:<id>`, built by
516		- // src/settings/item-placement.ts). sanitize_key() strips the colon,
517		- // which silently breaks the JS order match on reload and can collide
518		- // with an unrelated id — so allow the colon (and hyphen/underscore)
519		- // while still rejecting anything outside the JS id charset.
520		- $dock_order = array();
521		- if ( isset( $raw['dockOrder'] ) && is_array( $raw['dockOrder'] ) ) {
	930	+ // navOrder — ordered list of item ids, flat across every zone.
	931	+ // Reads the pre-navigation `dockOrder` when absent, stripping the
	932	+ // rail-synthesis prefixes (`dock:` / `desktop:`) that model no
	933	+ // longer has.
	934	+ $raw_order = array();
	935	+ if ( isset( $raw['navOrder'] ) && is_array( $raw['navOrder'] ) ) {
	936	+ $raw_order = $raw['navOrder'];
	937	+ } elseif ( isset( $raw['dockOrder'] ) && is_array( $raw['dockOrder'] ) ) {
	938	+ $raw_order = $raw['dockOrder'];
	939	+ }
	940	+
	941	+ $nav_order = array();
	942	+ if ( ! empty( $raw_order ) ) {
522	943	$seen = array();
523		- foreach ( $raw['dockOrder'] as $id ) {
	944	+ foreach ( $raw_order as $id ) {
524	945	if ( ! is_string( $id ) || '' === $id ) {
525	946	continue;
526	947	}
527		- $slug = (string) preg_replace( '/[^a-z0-9_:-]+/', '', strtolower( $id ) );
	948	+ $slug = sanitize_key( openstation_canonical_nav_id( $id ) );
528	949	if ( '' === $slug || isset( $seen[ $slug ] ) ) {
529	950	continue;
530	951	}
531	952	$seen[ $slug ] = true;
532		- $dock_order[] = $slug;
533		- if ( count( $dock_order ) >= 256 ) {
	953	+ $nav_order[] = $slug;
	954	+ if ( count( $nav_order ) >= 256 ) {
534	955	break;
535	956	}
536	957	}
537	958	}
		@@ -579,12 +1000,22 @@
579	1000
580	1001	return array(
581	1002	'wallpaper' => $wallpaper,
582	1003	'accent' => $accent,
	1004	+ 'customAccent' => $custom_accent,
583	1005	'dockSize' => $dock_size,
	1006	+ 'windowRadius' => $window_radius,
	1007	+ 'adminBarMode' => $admin_bar_mode,
584	1008	'desktopLayout' => $desktop_layout,
	1009	+ 'dockPlacement' => $dock_placement,
	1010	+ 'dockBehavior' => $dock_behavior,
	1011	+ 'sideDockBehavior' => $side_dock_behavior,
585	1012	'dockRailRenderer' => $dock_rail_renderer,
	1013	+ 'desktopTheme' => $desktop_theme,
	1014	+ 'appliedThemeRecommendations' => $applied_theme_recommendations,
586	1015	'unfocusEffect' => $unfocus_effect,
	1016	+ 'windowReveal' => $window_reveal,
	1017	+ 'windowRevealDuration' => $window_reveal_duration,
587	1018	'windowLinkRenderer' => $window_link_renderer,
588	1019	'windowLinkVisibility' => $window_link_visibility,
589	1020	'windowLinksEnabled' => $window_links_enabled,
590	1021	'windowLinkRaiseOnFocus' => $window_link_raise_on_focus,
		@@ -597,17 +1028,28 @@
597	1028	'heartbeatRate' => $heartbeat_rate,
598	1029	'nativePostsEnabled' => $native_posts_enabled,
599	1030	'nativePostsHiddenColumns' => $native_posts_hidden_columns,
600	1031	'nativePagesEnabled' => $native_pages_enabled,
	1032	+ 'nativePagesHiddenColumns' => $native_pages_hidden_columns,
601	1033	'nativeUsersEnabled' => $native_users_enabled,
602	1034	'nativePluginsEnabled' => $native_plugins_enabled,
603	1035	'nativeCommentsEnabled' => $native_comments_enabled,
	1036	+ 'stationHomeEnabled' => $station_home_enabled,
	1037	+ 'adminAssetCacheEnabled' => $admin_asset_cache_enabled,
	1038	+ 'windowPrewarmEnabled' => $window_prewarm_enabled,
604	1039	'showDesktopOnWallpaperClick' => $show_desktop_on_wallpaper_click,
	1040	+ 'confirmCloseAllWindows' => $confirm_close_all_windows,
	1041	+ 'mioEnabled' => $mio_enabled,
	1042	+ 'mioApiEnabled' => $mio_enabled,
	1043	+ 'mioShowOnWallpaper' => isset( $raw['mioShowOnWallpaper'] ) ? (bool) $raw['mioShowOnWallpaper'] : $defaults['mioShowOnWallpaper'],
	1044	+ 'mioStyle' => $mio_style,
605	1045	'showPostStatusRibbons' => $show_post_status_ribbons,
606	1046	'developerModeEnabled' => $developer_mode_enabled,
607	1047	'foldersSharingEnabled' => $folders_sharing_enabled,
608		- 'itemVisibility' => $item_visibility,
609		- 'dockOrder' => $dock_order,
	1048	+ 'navPlacement' => $nav_placement,
	1049	+ 'navOrder' => $nav_order,
	1050	+ 'mobileLayout' => $mobile_layout,
	1051	+ 'mobileTabs' => $mobile_tabs,
610	1052	'dockPromotedPositions' => $dock_promoted_positions,
611	1053	);
612	1054	}
613	1055
		@@ -612,12 +1054,10 @@
612	1054	}
613	1055
614	1056	/**
615	1057	* Registers the REST routes for OS settings.
616		- *
617		- * @since 0.5.0
618	1058	*/
619		-function desktop_mode_register_os_settings_rest_routes() {
	1059	+function openstation_register_os_settings_rest_routes() {
620	1060	register_rest_route(
621	1061	'desktop-mode/v1',
622	1062	'/os-settings',
623	1063	array(
		@@ -622,15 +1062,15 @@
622	1062	'/os-settings',
623	1063	array(
624	1064	array(
625	1065	'methods' => WP_REST_Server::READABLE,
626		- 'callback' => 'desktop_mode_rest_get_os_settings',
627		- 'permission_callback' => 'desktop_mode_rest_os_settings_permission',
	1066	+ 'callback' => 'openstation_rest_get_os_settings',
	1067	+ 'permission_callback' => 'openstation_rest_os_settings_permission',
628	1068	),
629	1069	array(
630	1070	'methods' => WP_REST_Server::CREATABLE,
631		- 'callback' => 'desktop_mode_rest_save_os_settings',
632		- 'permission_callback' => 'desktop_mode_rest_os_settings_permission',
	1071	+ 'callback' => 'openstation_rest_save_os_settings',
	1072	+ 'permission_callback' => 'openstation_rest_os_settings_permission',
633	1073	'args' => array(
634	1074	'settings' => array(
635	1075	'required' => true,
636	1076	'type' => 'object',
		@@ -639,49 +1079,90 @@
639	1079	),
640	1080	)
641	1081	);
642	1082	}
643		-add_action( 'rest_api_init', 'desktop_mode_register_os_settings_rest_routes' );
	1083	+add_action( 'rest_api_init', 'openstation_register_os_settings_rest_routes' );
644	1084
645	1085	/**
646	1086	* Permission gate for OS settings REST routes.
647	1087	*
648		- * Requires the caller to be logged in *and* have desktop mode enabled —
649		- * see {@see desktop_mode_rest_require_enabled()} for why `read` alone is
	1088	+ * Requires the caller to be logged in *and* have OpenStation enabled —
	1089	+ * see {@see openstation_rest_require_enabled()} for why `read` alone is
650	1090	* insufficient.
651	1091	*
652		- * @since 0.8.10 Hardened to require desktop mode enabled (was `read`).
653		- *
654	1092	* @return true|WP_Error
655	1093	*/
656		-function desktop_mode_rest_os_settings_permission() {
657		- return desktop_mode_rest_require_enabled();
	1094	+function openstation_rest_os_settings_permission() {
	1095	+ return openstation_rest_require_enabled();
658	1096	}
659	1097
660	1098	/**
661	1099	* GET /desktop-mode/v1/os-settings
662	1100	*
663		- * @since 0.5.0
664		- *
665	1101	* @return WP_REST_Response
666	1102	*/
667		-function desktop_mode_rest_get_os_settings() {
668		- return rest_ensure_response( desktop_mode_get_os_settings( get_current_user_id() ) );
	1103	+function openstation_rest_get_os_settings() {
	1104	+ return rest_ensure_response( openstation_get_os_settings( get_current_user_id() ) );
669	1105	}
670	1106
671	1107	/**
672	1108	* POST /desktop-mode/v1/os-settings
673	1109	*
674		- * @since 0.5.0
	1110	+ * Accepts a PARTIAL payload: keys the request omits keep the value
	1111	+ * already stored for the user, rather than resetting to the shipped
	1112	+ * default. The client sends only the fields that changed since its
	1113	+ * last confirmed save, which is what stops two open sessions from
	1114	+ * overwriting each other — a session that never touched the
	1115	+ * wallpaper cannot express an opinion about it, so a stale snapshot
	1116	+ * can no longer undo another session's unrelated change.
675	1117	*
	1118	+ * A full payload still behaves exactly as before: every key is
	1119	+ * present, so every key wins.
	1120	+ *
	1121	+ * The merge lives here rather than in {@see openstation_save_os_settings()}
	1122	+ * on purpose. That function's contract is REPLACE, and migrations
	1123	+ * depend on it: migration 1 in `includes/migrations.php` `unset()`s
	1124	+ * keys and re-saves precisely so the sanitizer backfills the new
	1125	+ * defaults. Give the saver merge semantics and that migration
	1126	+ * silently becomes a no-op.
	1127	+ *
	1128	+ * Merging is shallow, one level deep. For the map-shaped fields
	1129	+ * (`wallpaperSettings`, `navPlacement`, `navOrder`,
	1130	+ * `dockPromotedPositions`) a request that sends the key replaces the
	1131	+ * whole map — deep-merging them would leave no way to delete an
	1132	+ * entry.
	1133	+ *
676	1134	* @param WP_REST_Request $request The REST request.
677	1135	* @return WP_REST_Response The saved settings (after sanitization).
678	1136	*/
679		-function desktop_mode_rest_save_os_settings( WP_REST_Request $request ) {
	1137	+function openstation_rest_save_os_settings( WP_REST_Request $request ) {
680	1138	$user_id = get_current_user_id();
681	1139	$payload = $request->get_param( 'settings' );
682		- desktop_mode_save_os_settings( $user_id, $payload );
683		- return rest_ensure_response( desktop_mode_get_os_settings( $user_id ) );
	1140	+
	1141	+ // A payload that isn't an object says nothing about any field, so
	1142	+ // it changes nothing. The route declares `'settings' => object`
	1143	+ // and WP's schema validation rejects a scalar before the callback
	1144	+ // runs, so this is unreachable over real REST traffic — but the
	1145	+ // sanitizer resolves a non-array to the full defaults, which
	1146	+ // means the one way to reach this function with a bad payload
	1147	+ // used to be the one way to wipe a user's settings. Returning
	1148	+ // early costs nothing and keeps "don't destroy what wasn't sent"
	1149	+ // true of every path into this handler, not just the ones the
	1150	+ // schema happens to guard.
	1151	+ if ( ! is_array( $payload ) ) {
	1152	+ return rest_ensure_response( openstation_get_os_settings( $user_id ) );
	1153	+ }
	1154	+
	1155	+ // Normalize an alias-only patch before merging it with the saved master value.
	1156	+ if ( ! array_key_exists( 'mioEnabled', $payload ) && array_key_exists( 'mioApiEnabled', $payload ) ) {
	1157	+ $payload['mioEnabled'] = $payload['mioApiEnabled'];
	1158	+ }
	1159	+
	1160	+ openstation_save_os_settings(
	1161	+ $user_id,
	1162	+ array_merge( openstation_get_os_settings( $user_id ), $payload )
	1163	+ );
	1164	+ return rest_ensure_response( openstation_get_os_settings( $user_id ) );
684	1165	}
685	1166
686	1167	/**
687	1168	* Apply the per-user Heartbeat-rate preference to the
		@@ -689,17 +1170,15 @@
689	1170	* once at page load. We set `interval` only; the allowed rates
690	1171	* (15/30/45/60 s) all sit at or above Core's 15 s
691	1172	* `minimalInterval` floor, so the floor never needs overriding.
692	1173	*
693		- * Only applies to users with Desktop Mode enabled — non-desktop
	1174	+ * Only applies to users with OpenStation enabled — non-desktop
694	1175	* sessions keep Core's defaults. Anonymous requests skip too.
695	1176	*
696		- * @since 0.8.5
697		- *
698	1177	* @param array $settings Filtered Heartbeat settings.
699	1178	* @return array
700	1179	*/
701		-function desktop_mode_apply_heartbeat_rate_setting( $settings ) {
	1180	+function openstation_apply_heartbeat_rate_setting( $settings ) {
702	1181	if ( ! is_array( $settings ) ) {
703	1182	$settings = array();
704	1183	}
705	1184	$user_id = get_current_user_id();
		@@ -705,12 +1184,12 @@
705	1184	$user_id = get_current_user_id();
706	1185	if ( $user_id <= 0 ) {
707	1186	return $settings;
708	1187	}
709		- if ( function_exists( 'desktop_mode_is_enabled' ) && ! desktop_mode_is_enabled( $user_id ) ) {
	1188	+ if ( function_exists( 'openstation_is_enabled' ) && ! openstation_is_enabled( $user_id ) ) {
710	1189	return $settings;
711	1190	}
712		- $os = desktop_mode_get_os_settings( $user_id );
	1191	+ $os = openstation_get_os_settings( $user_id );
713	1192	$rate = isset( $os['heartbeatRate'] ) ? (int) $os['heartbeatRate'] : 0;
714	1193	if ( ! in_array( $rate, array( 15, 30, 45, 60 ), true ) ) {
715	1194	return $settings;
716	1195	}
		@@ -716,5 +1195,5 @@
716	1195	}
717	1196	$settings['interval'] = $rate;
718	1197	return $settings;
719	1198	}
720		-add_filter( 'heartbeat_settings', 'desktop_mode_apply_heartbeat_rate_setting' );
	1199	+add_filter( 'heartbeat_settings', 'openstation_apply_heartbeat_rate_setting' );