docs: install canonical Ferese specifications

README.md

@@ -2,7 +2,8 @@
 
 Ferese is an experimental Wayland tiling compositor written in Rust with
 Smithay. The nested compositor is complete and development currently targets
-the M1 native protocol and interaction milestone in [spec.md](spec.md).
+the M2 tiling and workspaces milestone in the
+[window-manager specification](docs/ferese-window-manager-spec.md).
 
 ## Development
 

docs/ferese-shell-design.md

@@ -0,0 +1,454 @@
+# Ferese Shell Design Specification
+
+Status: Draft for implementation  
+Target: Ferese desktop tier  
+Normative owner: shell behavior and interaction
+
+Companion documents:
+- `ferese-window-manager-spec.md` — compositor mechanism and policy
+- `ferese-theme-ui-spec.md` — visual tokens and exact component geometry
+
+## 1. Purpose
+
+`ferese-shell` provides the integrated desktop interface around Ferese-managed
+windows.
+
+The initial shell consists of:
+
+- one floating top bar per output;
+- an apps-only launcher;
+- overview controls;
+- top-bar popovers and a compact control center;
+- notifications and notification history; and
+- volume/brightness OSD.
+
+Ferese deliberately provides no persistent dock or bottom application bar.
+
+The shell MUST remain optional. If it crashes, managed windows, layout trees,
+workspaces, focus topology, and client sessions remain valid.
+
+## 2. Document boundaries
+
+This document owns:
+
+```text
+shell visibility
+layer-shell roles
+exclusive-zone behavior
+focus acquisition/restoration
+launcher behavior
+top-bar actions
+notification/DND behavior
+modal interaction
+fullscreen shell behavior
+shell restart behavior
+```
+
+It MUST NOT define raw colors, pixel heights, radii, blur amounts, icon sizes,
+font sizes, or shadows. Those belong to `ferese-theme-ui-spec.md`.
+
+## 3. Surface architecture
+
+The shell uses public layer-shell for normal shell surfaces.
+
+```text
+background(output)         background layer, optional
+top_bar(output)            top layer, exclusive zone
+launcher(output)           overlay layer, exclusive_zone = 0
+notification_stack(output) overlay layer, exclusive_zone = 0
+osd(output)                overlay layer, exclusive_zone = 0
+popover(output)            overlay/top, exclusive_zone = 0
+modal(output)              overlay layer, exclusive_zone = 0
+```
+
+`ferese-shell-v1` is a private control protocol only. It MUST NOT duplicate
+layer-shell geometry or roles.
+
+Its initial responsibilities are:
+
+```text
+window list and lifecycle
+application identity metadata
+focused / urgent state
+activate managed window
+request close
+enter / exit overview
+select overview window / workspace
+```
+
+## 4. Top bar
+
+A top bar exists on every active output unless disabled.
+
+Its conceptual regions are:
+
+```text
+LEFT
+    Ferese mark
+    workspace switcher
+    focused application
+
+CENTER
+    clock / date
+
+RIGHT
+    notifications
+    sound
+    power
+    control-center entry
+```
+
+The top bar is the only persistent shell surface that reserves workspace space.
+
+Workspace controls MUST use compositor workspace truth and ordinary Ferese
+workspace policy.
+
+The top bar SHOULD remain non-keyboard-interactive during ordinary use.
+
+## 5. Fullscreen behavior
+
+Entering fullscreen hides the top bar visually.
+
+The underlying tiled workspace layout region MUST remain unchanged while
+fullscreen is active.
+
+A temporary top-bar reveal over fullscreen:
+
+```text
+uses overlay presentation
+uses exclusive_zone = 0
+does not resize the fullscreen client
+does not mutate the underlying workspace layout
+```
+
+Leaving fullscreen restores the ordinary top-bar presentation without
+reconfiguring hidden tiled windows merely because the bar reappears.
+
+## 6. Shell reservation lease
+
+If `ferese-shell` disconnects unexpectedly, Ferese SHOULD retain the most recent
+valid Ferese-owned top-bar reservation for a short bounded grace period.
+
+If the shell reconnects before expiry with a compatible reservation, tiled
+windows MUST NOT reflow.
+
+If the grace period expires, Ferese removes the reservation and performs at most
+one ordinary layout reflow.
+
+Default:
+
+```text
+reservation_grace_ms = 2000
+```
+
+## 7. Launcher
+
+The initial launcher is apps-only.
+
+Default invocation:
+
+```text
+Super + Space
+```
+
+The launcher MAY also be opened by a Ferese control in the top bar.
+
+The launcher:
+
+- receives keyboard focus immediately;
+- discovers XDG desktop applications;
+- searches by application name and normalized desktop identity;
+- supports pointer and keyboard navigation;
+- launches selected applications with XDG activation;
+- dismisses on Escape; and
+- restores the previous valid managed-window focus on dismissal.
+
+Initial placeholder:
+
+```text
+Search apps…
+```
+
+The launcher MUST NOT expose dead tabs for files, settings, commands, or recents.
+
+Future search providers MAY extend it without changing the base interaction
+model.
+
+## 8. Application identity and launch state
+
+The launcher consumes the compositor's normalized application identity and launch
+association model.
+
+It MUST NOT assume strings such as:
+
+```text
+firefox
+org.mozilla.firefox
+Mozilla Firefox
+```
+
+are the same application unless desktop-entry or activation metadata establishes
+that relationship.
+
+Ferese does not maintain a persistent running-application strip.
+
+## 9. Top-bar popovers
+
+A top-bar control may own one anchored popover.
+
+Only one primary top-bar popover SHOULD be open per output at a time.
+
+Initial popovers MAY include:
+
+```text
+calendar / time
+sound
+battery / power status
+notifications
+control center
+```
+
+Network and Bluetooth configuration are not part of the initial desktop tier and
+MUST NOT appear as required or placeholder rows.
+
+Opening another primary popover closes the previous one on that output.
+
+## 10. Control center
+
+The initial control center MAY expose only services backed by real providers:
+
+```text
+sound
+battery / power status
+Do Not Disturb
+notification state
+Ferese Settings
+```
+
+Unavailable capabilities are omitted.
+
+## 11. Do Not Disturb
+
+When DND is off:
+
+```text
+eligible notifications may create transient toasts
+notifications enter history according to normal policy
+```
+
+When DND is on:
+
+```text
+normal transient toasts are suppressed
+notifications still enter history
+unread state still updates
+```
+
+A future explicitly defined critical-urgency policy MAY bypass DND.
+
+No application-name heuristic may bypass DND.
+
+DND state persists across shell restart.
+
+## 12. Notifications
+
+`ferese-shell` implements `org.freedesktop.Notifications`.
+
+Initial support:
+
+```text
+summary
+body
+icon metadata
+expiry
+replacement
+close
+actions
+urgency metadata
+```
+
+Notification content is untrusted.
+
+Transient toasts:
+
+- do not reserve workspace space;
+- appear beneath the top bar;
+- obey DND;
+- do not take keyboard focus by default.
+
+## 13. Notification center
+
+Notification history opens from the top bar.
+
+The initial implementation SHOULD use a large anchored popover rather than a
+permanent side drawer.
+
+The center may take shell keyboard focus while interactive and MUST restore the
+previous managed-window focus when dismissed.
+
+## 14. OSD
+
+OSD handles transient state such as:
+
+```text
+volume
+brightness
+microphone mute
+keyboard backlight
+```
+
+OSD surfaces:
+
+```text
+use overlay layer
+use exclusive_zone = 0
+never take keyboard focus
+dismiss automatically
+```
+
+## 15. Overview
+
+`Super+Tab` enters overview.
+
+Managed-window previews remain compositor-owned live scene nodes.
+
+The shell provides:
+
+```text
+selection affordances
+application/window labels
+workspace controls
+optional later search UI
+```
+
+The shell MUST NOT implement overview by continuously copying each managed
+window into the shell process.
+
+Window activation and close actions use `ferese-shell-v1`.
+
+## 16. Modal interaction
+
+Shell modals are reserved for:
+
+```text
+destructive confirmation
+security-sensitive confirmation
+irreversible shell action
+```
+
+Ordinary settings MUST NOT use shell modals.
+
+When a shell modal opens:
+
+```text
+SeatState.keyboard_focus -> FocusTarget::Shell(modal)
+```
+
+The compositor presents the modal above a scrim.
+
+Input outside the modal is consumed by the scrim and MUST NOT reach managed
+applications.
+
+On dismissal, the previous valid managed-window focus is restored.
+
+Ferese does not ship a polkit authentication agent in the initial desktop tier.
+
+## 17. Shell restart
+
+On restart:
+
+```text
+managed windows remain unchanged
+workspace assignments remain unchanged
+layout trees remain unchanged
+managed-window focus remains valid where possible
+```
+
+The restarted shell reconstructs:
+
+```text
+top bars
+workspace indicators
+focused-app metadata
+notification service/state
+DND state
+```
+
+from compositor truth and persistent shell state.
+
+## 18. Shell configuration
+
+Representative behavior-only configuration:
+
+```toml
+[shell]
+enabled = true
+reservation_grace_ms = 2000
+
+[shell.top_bar]
+enabled = true
+hide_in_fullscreen = true
+show_workspaces = true
+show_focused_app = true
+show_clock = true
+
+[shell.launcher]
+enabled = true
+binding = "Super+Space"
+
+[shell.overview]
+enabled = true
+binding = "Super+Tab"
+
+[shell.notifications]
+enabled = true
+do_not_disturb = false
+```
+
+Visual measurements do not belong here.
+
+## 19. First shell implementation slice
+
+```text
+top bar
+launcher
+one top-bar popover
+OSD
+```
+
+Demo:
+
+```text
+1. Start Ferese.
+2. Top bar appears.
+3. Workspace and focused-app state are correct.
+4. Press Super+Space.
+5. Launcher opens and receives focus.
+6. Search for Foot and launch it.
+7. Foot enters the current workspace through normal tiling policy.
+8. Open Sound from the top bar.
+9. Sound popover anchors to its invoking control.
+10. Enter fullscreen.
+11. Top bar hides without changing the underlying tiled layout region.
+12. Reveal top bar temporarily as an overlay.
+13. Exit fullscreen.
+14. Top bar returns to normal reserved presentation.
+15. Restart ferese-shell.
+16. Tiled windows do not reflow during the reservation grace period.
+```
+
+## 20. Completion criteria
+
+The initial shell is complete when:
+
+1. every active output has a functional top bar;
+2. launcher search and application launching work;
+3. workspace indicators reflect compositor truth;
+4. focused application state is accurate;
+5. top-bar popovers anchor correctly;
+6. notifications and DND work;
+7. OSD works without taking focus;
+8. overview uses compositor-owned live windows;
+9. fullscreen hide/reveal does not alter underlying layout geometry;
+10. shell restart does not disturb managed windows; and
+11. all visual presentation is supplied through the theme/UI token system.

docs/ferese-theme-ui-spec.md

@@ -0,0 +1,807 @@
+# Ferese Theme and UI Specification
+
+Status: Draft for implementation  
+Target: Ferese desktop tier  
+Normative owner: visual tokens and component geometry
+
+Companion documents:
+- `ferese-window-manager-spec.md` — compositor mechanism and policy
+- `ferese-shell-design.md` — shell behavior and interaction
+
+## 1. Purpose
+
+This document defines the Ferese visual language.
+
+It owns:
+
+- desktop background treatment;
+- color tokens;
+- semantic surface tokens;
+- typography;
+- iconography;
+- spacing;
+- exact top-bar geometry;
+- launcher geometry;
+- popover/menu/modal geometry;
+- notification geometry;
+- OSD geometry;
+- settings UI primitives;
+- motion tokens; and
+- glass, translucent, and solid visual profiles.
+
+It does not define shell focus, fullscreen behavior, workspace policy, launcher
+behavior, notification policy, or compositor security.
+
+Ferese intentionally has no persistent dock or bottom application bar.
+
+## 2. Design language
+
+Ferese UI should feel:
+
+```text
+quiet
+precise
+soft
+material
+low-latency
+high-contrast
+spatially consistent
+```
+
+The shell MUST avoid:
+
+- excessive glow;
+- RGB/gamer styling;
+- ornamental gradients;
+- gratuitous transparency;
+- oversized shadows;
+- arbitrary component styling;
+- large chrome that steals workspace area; and
+- pixel-for-pixel imitation of another operating system.
+
+Ferese must still look complete with blur disabled.
+
+## 3. Theme model
+
+Components request semantic surface roles:
+
+```text
+surface.panel
+surface.panel_elevated
+surface.popover
+surface.menu
+surface.notification
+surface.hud
+surface.modal
+```
+
+The active profile maps each role to material parameters.
+
+Themes change appearance, not component structure or behavior.
+
+## 4. Material styles
+
+```rust
+pub enum MaterialStyle {
+    Glass,
+    Translucent,
+    Solid,
+}
+```
+
+### Glass
+
+Backdrop blur plus restrained tint, saturation, brightness, and optional noise.
+
+### Translucent
+
+Alpha-composited semantic tint with no backdrop blur.
+
+### Solid
+
+Opaque semantic surface with identical geometry.
+
+Changing material style MUST NOT move, resize, or restructure shell components.
+
+## 5. Built-in profiles
+
+```text
+ferese-glass
+ferese-translucent
+ferese-solid
+```
+
+All share:
+
+```text
+component geometry
+spacing
+typography
+icon metrics
+interaction states
+motion semantics
+```
+
+## 6. Background
+
+Supported:
+
+```text
+solid color
+image fill
+image fit
+```
+
+Ferese SHOULD NOT globally blur the wallpaper.
+
+Optional restrained adjustments MAY include:
+
+```text
+brightness
+dimming
+saturation
+```
+
+Default fallback:
+
+```text
+#0B0F14
+```
+
+## 7. Color tokens
+
+Representative dark profile:
+
+```toml
+[theme.colors]
+desktop_background = "#0B0F14"
+
+surface_base = "#111821"
+surface_raised = "#18212C"
+surface_elevated = "#202B37"
+
+text_primary = "#F4F7FB"
+text_secondary = "#B7C0CB"
+text_muted = "#7F8A98"
+text_disabled = "#58616D"
+
+accent = "#5B8CFF"
+accent_soft = "#8EAFFF"
+accent_text = "#FFFFFF"
+
+success = "#4CC38A"
+warning = "#F0B45B"
+danger = "#F06A6A"
+
+border = "#FFFFFF18"
+border_strong = "#FFFFFF2A"
+
+shadow = "#00000055"
+scrim = "#05070AB8"
+```
+
+## 8. Surface tokens
+
+Representative glass profile:
+
+```toml
+[theme.surface.panel]
+style = "glass"
+opacity = 0.78
+blur = 24.0
+saturation = 1.08
+brightness = 1.02
+noise = 0.012
+border_opacity = 0.10
+shadow = "soft"
+
+[theme.surface.panel_elevated]
+style = "glass"
+opacity = 0.84
+blur = 28.0
+saturation = 1.10
+brightness = 1.03
+noise = 0.014
+border_opacity = 0.12
+shadow = "elevated"
+
+[theme.surface.popover]
+style = "glass"
+opacity = 0.84
+blur = 28.0
+saturation = 1.10
+brightness = 1.03
+noise = 0.014
+border_opacity = 0.12
+shadow = "elevated"
+
+[theme.surface.hud]
+style = "glass"
+opacity = 0.88
+blur = 30.0
+saturation = 1.06
+brightness = 1.04
+noise = 0.010
+border_opacity = 0.12
+shadow = "elevated"
+```
+
+## 9. Geometry tokens
+
+```toml
+[theme.geometry]
+base_unit = 8.0
+
+window_radius = 14.0
+
+top_bar_height = 32.0
+top_bar_margin_top = 8.0
+top_bar_margin_horizontal = 10.0
+top_bar_radius = 16.0
+
+launcher_width = 560.0
+launcher_radius = 20.0
+
+popover_radius = 16.0
+menu_radius = 14.0
+modal_radius = 18.0
+hud_radius = 18.0
+
+panel_padding = 12.0
+control_gap = 8.0
+section_gap = 16.0
+```
+
+Only the top bar consumes persistent shell space.
+
+## 10. Typography
+
+Initial roles:
+
+```text
+caption       11-12 px
+body          13-14 px
+body-strong   13-14 px medium
+label         12-13 px medium
+title         16-18 px semibold
+display       22-28 px semibold
+```
+
+Use the system UI sans-serif by default.
+
+Clocks and changing numeric values SHOULD use tabular numerals where available.
+
+## 11. Iconography
+
+System icons are monochrome vectors.
+
+```text
+visual box      16-20 px
+stroke          approximately 1.5-2 px
+style           simple and optically balanced
+```
+
+Application icons retain original artwork.
+
+System icons MUST NOT use arbitrary gradients.
+
+## 12. Top bar
+
+Default composition:
+
+```text
+╭──────────────────────────────────────────────────────────────╮
+│ F   1  2  3   4      Zed              09:41        🔊   ◉  │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+Surface role:
+
+```text
+surface.panel
+```
+
+### Workspace state
+
+Inactive workspaces use muted text.
+
+Active workspace uses a compact filled or accent-backed indicator.
+
+### Focused application
+
+May display:
+
+```text
+application icon
+application name
+```
+
+Full changing window titles are not part of the default bar.
+
+### Clock
+
+Compact:
+
+```text
+09:41
+```
+
+Optional wide:
+
+```text
+Mon, Sep 23   09:41
+```
+
+## 13. Launcher
+
+The launcher is the primary application-selection surface.
+
+Default placement:
+
+```text
+centered horizontally
+upper-middle or center of usable workspace
+```
+
+Surface role:
+
+```text
+surface.panel_elevated
+```
+
+Default geometry:
+
+```text
+width       theme.geometry.launcher_width
+max height  70% of usable output
+radius      theme.geometry.launcher_radius
+```
+
+Initial content:
+
+```text
+╭──────────────────────────────────────╮
+│ Search apps…                         │
+├──────────────────────────────────────┤
+│                                      │
+│  Zed      Firefox      Foot          │
+│  Files    Settings     Music         │
+│                                      │
+╰──────────────────────────────────────╯
+```
+
+Initial implementation is apps-only.
+
+## 14. Launcher search field
+
+```text
+height      44-48 px
+radius      12 px
+```
+
+Placeholder:
+
+```text
+Search apps…
+```
+
+The search field is the visual focus.
+
+## 15. Launcher application grid
+
+Recommended:
+
+```text
+4-6 columns depending on launcher width
+```
+
+Entries show:
+
+```text
+application icon
+one-line application name
+```
+
+Long names truncate with ellipsis.
+
+## 16. Top-bar popovers
+
+Surface:
+
+```text
+surface.popover
+```
+
+Recommended:
+
+```text
+width            280-360 px
+padding          12 px
+radius           theme.geometry.popover_radius
+anchor gap       8 px
+```
+
+They visually align with the invoking top-bar control.
+
+## 17. Control center
+
+Representative:
+
+```text
+╭──────────────────────────────╮
+│ Sound                        │
+│ ━━━━━━━━━━━●━━━━━━          │
+│                              │
+│ Battery              92%     │
+│ Do Not Disturb        Off    │
+│ Notifications          3     │
+│                              │
+│ Ferese Settings              │
+╰──────────────────────────────╯
+```
+
+Network/Bluetooth rows are not part of the initial visual contract.
+
+## 18. Menus
+
+Menus use:
+
+```text
+surface.menu
+```
+
+Row:
+
+```text
+icon   label                         shortcut
+```
+
+Disabled items use `text_disabled`.
+
+## 19. Modals
+
+Modals use:
+
+```text
+surface.modal
+```
+
+Default width:
+
+```text
+360-480 px
+```
+
+Background scrim uses `theme.colors.scrim`.
+
+Modal visuals do not imply a Ferese authentication agent.
+
+## 20. Notifications
+
+Toast surface:
+
+```text
+surface.notification
+```
+
+Recommended width:
+
+```text
+320-360 px
+```
+
+Structure:
+
+```text
+icon
+summary
+body
+time
+optional actions
+```
+
+Newest appears nearest the top bar.
+
+## 21. OSD
+
+Surface:
+
+```text
+surface.hud
+```
+
+Example:
+
+```text
+╭──────────────────────╮
+│ 🔊  ━━━━━━━●━━━━━   │
+╰──────────────────────╯
+```
+
+Default placement is centered or lower-middle.
+
+## 22. Overview chrome
+
+Managed windows remain live compositor surfaces.
+
+Theme/UI owns only:
+
+```text
+selection ring
+labels
+workspace strip
+scrim
+overview control surfaces
+```
+
+Selected preview uses an accent ring, not a large glow.
+
+## 23. Interaction states
+
+Controls support:
+
+```text
+rest
+hover
+pressed
+focused
+selected
+disabled
+urgent where applicable
+```
+
+Hover changes color/contrast only.
+
+Pressed controls MAY use a tiny local scale response around `0.98`.
+
+There is no dock-style magnification behavior.
+
+## 24. Focus rings
+
+Keyboard focus:
+
+```text
+2 px accent ring
+2 px visual separation where needed
+```
+
+Focus rings MUST NOT alter component geometry.
+
+## 25. Shadows
+
+Levels:
+
+```text
+none
+soft
+elevated
+```
+
+Representative:
+
+```toml
+[theme.shadow.soft]
+offset_y = 4.0
+blur = 18.0
+opacity = 0.20
+
+[theme.shadow.elevated]
+offset_y = 10.0
+blur = 36.0
+opacity = 0.28
+```
+
+Top bar uses `soft`.
+
+Launcher, popovers, notifications, modals, and HUDs typically use `elevated`.
+
+## 26. Borders
+
+Default:
+
+```text
+1 logical px
+```
+
+Glass uses subtle highlight borders.
+
+Solid may use slightly stronger borders.
+
+Borders MUST NOT resemble neon outlines.
+
+## 27. Motion tokens
+
+```text
+spatial spring
+bounded easing
+```
+
+Approximate ranges:
+
+```text
+micro feedback      80-120 ms
+popover/menu        140-200 ms
+launcher            180-240 ms
+notification        160-220 ms
+```
+
+Managed-window and overview motion remains compositor spring-driven.
+
+## 28. Reduced motion
+
+Reduced motion:
+
+```text
+removes decorative scale
+shortens/removes large shell translation
+uses opacity where spatial context is unnecessary
+does not animate blur intensity
+```
+
+## 29. Fullscreen visual presentation
+
+When fullscreen is active, the top bar is visually absent.
+
+Temporary reveal uses the same visual tokens without implying any layout change.
+
+## 30. Settings application
+
+Ferese Settings consumes the same tokens.
+
+Representative layout:
+
+```text
+╭──────────────────────────────────────────────╮
+│ sidebar         │ content                    │
+│                 │                            │
+│ General         │ Appearance                 │
+│ Appearance      │                            │
+│ Tiling          │ live preview               │
+│ Workspaces      │ controls                   │
+│ Shortcuts       │                            │
+│ Input           │                            │
+╰──────────────────────────────────────────────╯
+```
+
+## 31. Appearance settings
+
+Expose:
+
+```text
+material style
+accent
+corner radius
+shadow intensity
+glass blur
+glass opacity
+animation speed
+reduced motion
+```
+
+Material style:
+
+```text
+Glass
+Translucent
+Solid
+```
+
+Changing style MUST preserve geometry.
+
+## 32. Theme configuration
+
+```toml
+[theme]
+profile = "ferese-glass"
+mode = "dark"
+
+[theme.colors]
+accent = "#5B8CFF"
+
+[theme.material]
+style = "glass"
+
+[theme.material.glass]
+blur = 24.0
+opacity = 0.80
+saturation = 1.08
+noise = 0.012
+
+[theme.geometry]
+window_radius = 14.0
+top_bar_height = 32.0
+top_bar_radius = 16.0
+launcher_width = 560.0
+launcher_radius = 20.0
+
+[theme.motion]
+speed = 1.0
+reduced_motion = false
+```
+
+## 33. Validation
+
+Reject:
+
+```text
+non-finite dimensions
+negative radii
+negative blur
+opacity outside 0..1
+invalid colors
+unknown material style
+invalid font sizes
+invalid motion factors
+```
+
+Theme changes use the same transactional Ferese configuration path.
+
+## 34. Custom theme scope
+
+Themes MAY change:
+
+```text
+colors
+material parameters
+radii
+shadows
+typography
+accent
+icon tint
+motion scale
+validated component geometry tokens
+```
+
+Themes MUST NOT change:
+
+```text
+top-bar behavior
+launcher behavior
+focus behavior
+workspace behavior
+notification policy
+Wayland roles
+security behavior
+```
+
+Ferese intentionally does not expose arbitrary CSS.
+
+## 35. Performance degradation
+
+Priority:
+
+```text
+1. geometry correctness
+2. input latency
+3. text/icon clarity
+4. animation continuity
+5. shadow quality
+6. blur quality
+7. decorative effects
+```
+
+Allowed degradation:
+
+```text
+glass
+    -> lower-resolution glass
+    -> translucent
+    -> solid
+```
+
+Component geometry remains unchanged.
+
+## 36. Visual acceptance criteria
+
+Implementation succeeds when:
+
+1. top bar, launcher, popovers, notifications, OSD, overview chrome, and Settings
+   share one spacing/material/typography system;
+2. glass, translucent, and solid profiles preserve geometry;
+3. typography remains readable on bright and dark backgrounds;
+4. icons have consistent optical weight;
+5. launcher and popovers look anchored and intentional;
+6. focus/selection/urgent states remain distinct without relying on glow;
+7. disabling blur does not make the desktop look unfinished;
+8. reduced-motion mode remains coherent; and
+9. the desktop feels complete without a persistent dock or bottom application bar.

docs/ferese-window-manager-spec.md

@@ -9,7 +9,7 @@ Display protocol: Wayland
 
 Ferese is a Wayland tiling compositor for a conventional, keyboard-friendly
 desktop. It combines predictable window management with compositor-owned rounded
-geometry, shadows, animation, transparency, and semantic glass materials.
+geometry, shadows, animation, transparency, and semantic surface materials.
 
 This document is the implementation source of truth for Ferese v0 and records
 the gated desktop-tier roadmap. The terms **MUST**, **MUST NOT**, **SHOULD**,
@@ -26,6 +26,24 @@ the gated desktop-tier roadmap. The terms **MUST**, **MUST NOT**, **SHOULD**,
 7. The nested compositor is the primary development environment.
 8. Security-sensitive operations are unavailable to untrusted clients.
 
+### 2.1 Companion specification ownership
+
+Ferese uses three normative documents with non-overlapping ownership:
+
+| Concern | Normative owner |
+| --- | --- |
+| compositor mechanism, Wayland policy, focus, layout, rendering, IPC, security | this document |
+| shell interaction, visibility, launcher, notifications, DND, shell focus | `ferese-shell-design.md` |
+| colors, semantic surface tokens, typography, icons, and exact shell component geometry | `ferese-theme-ui-spec.md` |
+
+The shell specification MUST reference visual tokens instead of duplicating
+pixel, radius, color, shadow, blur, or typography values. The theme/UI
+specification MUST NOT redefine focus, fullscreen, workspace, launcher,
+notification, or security behavior.
+
+If companion documents conflict, the owner in this table is authoritative for
+that concern.
+
 ## 3. Scope
 
 ### 3.1 v0 core requirements
@@ -58,8 +76,8 @@ for basic window management or application launching.
 
 The desktop tier builds on the v0 core and includes:
 
-- backdrop blur and semantic glass materials;
+- semantic surface materials with glass, translucent, and solid rendering;
-- the Ferese overview, launcher UI, workspace strip, OSD, and notifications;
+- the Ferese top bar, overview, launcher UI, workspace UI, OSD, and notifications;
 - the graphical settings application;
 - portal-backed screenshots and screen sharing; and
 - X11 compatibility through `xwayland-satellite` unless an architectural
@@ -73,8 +91,8 @@ terminating the compositor or invalidating managed-window state.
 The following are outside v0:
 
 - a file manager, display manager, or lock screen;
-- network, Bluetooth, or package-management UI;
+- network, Bluetooth, or package-management UI in v0 or the initial desktop-tier shell;
-- a general plugin, scripting, or theme system;
+- a general plugin or scripting system, or arbitrary CSS/component-replacement theme engine;
 - desktop widgets;
 - advanced dynamic layout algorithms;
 - exhaustive support for every Wayland protocol or toolkit edge case; and
@@ -90,7 +108,7 @@ daemon is not part of v0.
 | Executable | Responsibility |
 | --- | --- |
 | `ferese` | Compositing, policy, input, scene construction, and rendering |
-| `ferese-shell` | Overview controls, launcher, workspace UI, notifications, and OSD |
+| `ferese-shell` | Top bar, overview controls, launcher, workspace UI, notifications, and OSD |
 | `ferese-settings` | Graphical configuration editor |
 | `feresectl` | Command-line IPC client |
 
@@ -372,6 +390,40 @@ set initial workspace, floating state, dimensions, or fullscreen state. Rules
 MUST be evaluated deterministically before insertion. Title matching SHOULD be
 avoided when a stable `app_id` exists.
 
+### 5.5 Application identity and launch association
+
+Ferese exposes normalized application identity to trusted shell clients without
+making application identity part of layout policy.
+
+```rust
+pub struct ApplicationIdentity {
+    pub desktop_id: Option<String>,
+    pub app_id: Option<String>,
+    pub startup_wm_class: Option<String>,
+}
+
+pub struct LaunchAssociation {
+    pub id: LaunchId,
+    pub desktop_id: Option<String>,
+    pub activation_token: Option<String>,
+    pub child_pid: Option<u32>,
+    pub started_at: Instant,
+}
+```
+
+Application identity resolution MUST prefer explicit desktop-entry association,
+then normalized Wayland `app_id`, then `StartupWMClass`/X11 class metadata when
+available. Ferese MUST NOT guess that unrelated strings are equivalent merely
+because they are similar. Case and an optional `.desktop` suffix MAY be
+normalized only where desktop-entry semantics make that comparison unambiguous.
+
+A shell-initiated launch MUST be tracked until the resulting window is
+associated or the launch expires. XDG activation information is the preferred
+association; process ancestry and normalized application identity MAY be used as
+fallbacks. The association exists to drive shell state such as `launching`,
+`running`, and focus. It MUST NOT bypass ordinary window rules or workspace
+policy.
+
 ## 6. Layout
 
 ```rust
@@ -617,149 +669,256 @@ intermediates rather than full-resolution per-frame blur.
 
 ## 10. Material system
 
-This section specifies the desktop-tier material system. It is not a v0 release
+This section specifies compositor support for desktop-tier semantic surfaces. It
-gate.
+is not a v0 release gate. Theme token values and exact component geometry belong
+to `ferese-theme-ui-spec.md`.
 
-Initial semantic materials are:
+Initial semantic surface roles are:
 
 ```text
-normal
+surface.panel
-glass.panel
+surface.panel_elevated
-glass.popover
+surface.popover
-glass.menu
+surface.menu
-glass.hud
+surface.notification
+surface.hud
+surface.modal
 ```
 
-The compositor maps semantic names to theme-controlled parameters. Clients
+Clients request semantic roles rather than raw shader values.
-SHOULD request names rather than shader values.
+
+The compositor resolves each role through the active material style:
+
+```rust
+pub enum MaterialStyle {
+    Glass,
+    Translucent,
+    Solid,
+}
+```
 
 `ferese-effects-v1` is private to trusted Ferese components. It MAY set or clear
-a semantic surface material. It MUST NOT expose shader code, unrestricted
+a semantic surface role. It MUST NOT expose shader code, unrestricted capture,
-capture, or unbounded effect values. Its global MUST be advertised only to
+arbitrary renderer state, or unbounded effect values. Its global MUST be
-Wayland clients granted the `effects` capability by the private-client mechanism
+advertised only to Wayland clients granted the `effects` capability by the
-in Section 13.
+private-client mechanism in Section 13.
 
-Glass renders as:
+For `Glass`, the compositor-owned rendering pipeline is:
 
 ```text
 lower scene content
   -> capture expanded region
   -> downsample
-  -> dual Kawase blur
+  -> blur
   -> upsample
   -> saturation and brightness
-  -> tint and noise
+  -> tint and optional noise
-  -> glass foreground
+  -> semantic surface foreground
 ```
 
-Blur MUST exclude the glass surface and all content above it. Sampling bounds
+Blur MUST exclude the requesting surface and all content above it. Sampling
-MUST include the kernel radius.
+bounds MUST include the kernel radius.
+
+For `Translucent`, the compositor applies semantic tint and alpha without
+backdrop capture. For `Solid`, the compositor uses an opaque semantic surface
+color. Changing material style MUST NOT change component geometry, focus, input
+regions, layer-shell roles, or shell behavior.
 
 A blur cache entry MUST identify its output and scale, visible and sample
-regions, material parameters, contributing lower-layer generations, and result
+regions, semantic role and resolved material parameters, contributing
-texture. Changes to content, stacking, geometry, scale, transform, material,
+lower-layer generations, and result texture. Changes to content, stacking,
-workspace, or output MUST invalidate affected entries. A global generation MAY
+geometry, scale, transform, resolved material, workspace, or output MUST
-be used initially; region-aware invalidation SHOULD replace it before performance
+invalidate affected entries. A global generation MAY be used initially;
-tuning is complete.
+region-aware invalidation SHOULD replace it before performance tuning is
+complete.
 
 ### 10.1 Built-in visual profile
 
-The desktop tier provides one restrained dark profile rather than a theme
+The desktop tier provides one restrained Ferese visual language with glass,
-engine. Its defaults are a subtle blue focus accent, 14 logical-pixel window
+translucent, and solid profiles. Exact values for colors, radii, shadows,
-radius, 10 logical-pixel tiling gaps, soft shadows, 24 logical-pixel backdrop
+typography, spacing, and material parameters are normative only in
-blur, and mildly increased glass saturation. Focused and foreground content MUST remain distinguishable
+`ferese-theme-ui-spec.md`.
-without requiring transparency. Blur, glow, borders, and shadows SHOULD establish
+
-hierarchy rather than compete for attention. Settings, overview, notifications,
+Focused and foreground content MUST remain distinguishable without transparency.
-launcher, and OSD MUST use the same semantic materials and spacing system.
+Blur, borders, and shadows SHOULD establish hierarchy rather than compete for
+attention. Settings, top bar, overview chrome, notifications, launcher, popovers,
+and OSD MUST consume the same semantic surface and spacing tokens.
 
 ## 11. Shell and overview
 
-This section specifies desktop-tier behavior. `ferese-shell` owns overview
+This section specifies compositor-facing desktop-tier shell behavior. Detailed
-controls, launcher, workspace strip, notifications, and volume and brightness
+interaction is normative in `ferese-shell-design.md`; visual tokens and exact
-OSD. Screenshot UI MAY be added after capture policy and implementation are
+component geometry are normative in `ferese-theme-ui-spec.md`.
-complete. The shell uses a capability-scoped private Wayland connection plus
+
-authenticated IPC.
+`ferese-shell` owns the top bar, overview controls, launcher, workspace UI,
+notifications, and volume and brightness OSD. Screenshot UI MAY be added after
+capture policy and implementation are complete. The shell uses a
+capability-scoped private Wayland connection plus authenticated IPC.
+
+Ferese deliberately has no persistent dock or bottom application bar.
 
 Overview MUST NOT require copying each managed window into the shell process.
 The compositor owns the live window presentation and enters an overview scene
 mode in which existing window scene nodes receive temporary visual transforms.
-`ferese-shell` supplies controls such as labels, selection affordances, workspace
+`ferese-shell` supplies controls such as labels, selection affordances,
-UI, and later search.
+workspace UI, and later search.
 
 The overview binding is `Super+Tab`. Entering overview MUST animate windows from
 their current visible geometry into overview geometry. Pointer and keyboard
-selection MUST target the compositor-owned live window nodes. Dismissing overview
+selection MUST target the compositor-owned live window nodes. Dismissing
-MUST animate those same nodes back to the current layout targets. Workspace
+overview MUST animate those same nodes back to the current layout targets.
-switching from overview MUST obey Section 5.4. Search MAY wait for the launcher
+Workspace switching from overview MUST obey Section 5.4.
-milestone.
 
-### 11.1 Shell surfaces
+### 11.1 Public layer-shell
 
-`ferese-shell` MUST use standard layer-shell for launcher, workspace UI,
+`ferese-shell` MUST use standard layer-shell for the top bar, launcher,
-notifications, and OSD surfaces. Such a surface is not a managed application
+workspace UI, notifications, popovers, and OSD surfaces. Such surfaces are not
-window and MUST NOT enter tiling, workspace focus history, or normal application
+managed application windows and MUST NOT enter tiling, workspace focus history,
-task switching. Ferese MAY use a minimal private `ferese-shell-v1` protocol for
+or normal application task switching.
-overview control and compositor-owned live-window selection, but it MUST NOT
-duplicate the standard layer-shell role or geometry model.
 
-Initial semantic roles are:
+Layer-shell is a public standard role and remains available to ordinary
+third-party panels, launchers, notification daemons, and wallpapers under
+Section 8 policy. Binding layer-shell MUST NOT grant Ferese-specific metadata,
+overview control, capture, virtual input, or semantic-surface capability.
+
+The compositor enforces layer, exclusive-zone, keyboard-interactivity,
+input-region, namespace, and output policy.
+
+### 11.2 Top bar, fullscreen, and reservation
+
+The Ferese top bar is the only persistent Ferese shell surface that reserves
+workspace space.
+
+Fullscreen is a presentation state over the preserved underlying workspace
+layout. Entering fullscreen MUST hide the Ferese top bar visually without
+changing the underlying workspace usable layout region. Leaving fullscreen MUST
+restore the bar without reconfiguring hidden tiled windows merely because the
+bar reappears.
+
+A temporary top-bar reveal over fullscreen MUST use overlay presentation and
+`exclusive_zone = 0`. It MUST NOT resize the fullscreen client or alter the
+underlying workspace layout.
+
+If `ferese-shell` disconnects unexpectedly, the compositor SHOULD retain the
+last valid Ferese-owned top-bar reservation for a short bounded grace period.
+If the shell reconnects with a compatible reservation before the lease expires,
+tiled windows MUST NOT reflow. If the grace period expires, Ferese removes the
+reservation and performs at most one ordinary layout reflow.
+
+### 11.3 Private shell control protocol
+
+`ferese-shell-v1` is a private control and metadata protocol. It MUST NOT
+duplicate layer-shell roles, exclusive zones, or general surface placement.
+
+Its initial responsibilities are limited to:
 
 ```text
-launcher
+managed-window list and lifecycle
-overview-controls
+application identity metadata
-workspace-ui
+focused and urgent state
-notification
+activate managed window
-osd
+request close
+enter / exit overview
+select overview window / workspace
 ```
 
-The compositor enforces layer, exclusive-zone, focus, input-region, and output
+The protocol requires the `shell-control` capability from Section 13. Requests
-policy. The shell provides content and requests a standard layer-shell role; it
+MUST be validated against current stable identifiers and flow through the same
-MUST NOT receive unrestricted arbitrary z-order or geometry authority.
+domain operations as keyboard, pointer, and IPC actions.
-Interactive shell surfaces MAY receive keyboard/pointer focus while active, but
-Ferese MUST restore the prior managed-window focus when the interaction ends.
-Destroying or disconnecting the shell client MUST remove its shell surfaces
-without changing managed-window state.
 
-### 11.2 Application launching and notifications
+### 11.4 Launcher and application launching
 
-The launcher MUST execute configured argument vectors directly and MUST NOT pass
+The initial Ferese launcher is apps-only. Its default binding is `Super+Space`.
-them through a shell. Before launch, it MUST obtain an xdg-activation token tied
+It discovers XDG desktop applications, searches application names and normalized
-to the triggering user interaction and make the token available to the child.
+application identity, and launches selected applications.
-The child receives the public Wayland display and normal session environment.
+
-It MUST NOT inherit a private Wayland descriptor, IPC capability, or bearer
+The initial search placeholder is:
-secret. A private descriptor deliberately inherited when the compositor starts a
+
-trusted component is the sole exception during that component's initial exec;
+```text
-the component MUST mark it close-on-exec before it can launch any child.
+Search apps…
+```
+
+Files, recents, settings, and command providers MAY be added later. The shell
+MUST NOT display dead tabs for unavailable providers.
+
+Before launch, the shell MUST obtain an xdg-activation token tied to the
+triggering user interaction and make the token available to the child. The child
+receives the public Wayland display and normal session environment. It MUST NOT
+inherit a private Wayland descriptor, IPC capability, or bearer secret.
+
+A private descriptor deliberately inherited when the compositor starts a trusted
+component is the sole exception during that component's initial exec; the
+component MUST mark it close-on-exec before it can launch any child.
+
+### 11.5 Shell focus and modals
+
+Interactive shell surfaces MAY receive `FocusTarget::Shell`. The persistent top
+bar SHOULD remain non-keyboard-interactive during ordinary use.
+
+The launcher receives keyboard focus while open and MUST restore the previous
+valid managed-window focus on dismissal where possible. Interactive popovers and
+modals follow the same restoration rule.
+
+A shell modal is appropriate only for destructive confirmation,
+security-sensitive confirmation, or an irreversible shell action. While a modal
+is active, the compositor presents a scrim and directs keyboard focus to the
+modal. Input outside the modal is consumed by the scrim and MUST NOT reach
+managed applications.
+
+Destroying a shell surface or disconnecting the shell MUST never leave a dead
+`FocusTarget::Shell`.
+
+Ferese does not ship a polkit authentication agent in the initial desktop tier.
+System authentication requiring polkit uses an external agent until a separate
+authentication-agent security specification exists.
+
+### 11.6 Notifications and Do Not Disturb
 
 `ferese-shell` MUST implement the standard `org.freedesktop.Notifications` D-Bus
 service for basic notifications. The desktop tier MUST support summary, body,
-icon metadata, expiry, replacement, close, and actions. Notification content is untrusted:
+icon metadata, expiry, replacement, close, actions, and urgency metadata.
-markup, image paths, and action identifiers MUST be parsed and rendered without
+
-command execution. If the shell restarts, it MUST reacquire the service and
+Notification content is untrusted: markup, image paths, and action identifiers
-continue without affecting managed windows.
+MUST be parsed and rendered without command execution.
+
+When Do Not Disturb is disabled, eligible notifications MAY create transient
+toasts and enter notification history. When Do Not Disturb is enabled, normal
+transient toasts are suppressed but notifications still enter history and
+unread state still updates. A future explicitly defined critical-urgency policy
+MAY bypass DND; application-name heuristics MUST NOT.
+
+Network and Bluetooth control UI are outside the initial desktop-tier shell and
+MUST NOT appear as required or placeholder controls.
+
+If the shell restarts, it MUST reacquire the notification service and reconstruct
+shell state without affecting managed windows.
 
 ## 12. Configuration
 
 The primary file is `$XDG_CONFIG_HOME/ferese/config.toml`, falling back to
 `~/.config/ferese/config.toml`.
 
+Configuration has one authoritative representation. Namespace ownership is:
+
+```text
+[theme.*]         visual tokens/material mapping   ferese-theme-ui-spec.md
+[shell.*]         shell behavior                   ferese-shell-design.md
+
+[animations]      compositor animation policy      this document
+[tiling]          layout policy                    this document
+[input]           input policy                     this document
+[commands]        launch command vectors           this document
+[[bindings]]      compositor bindings              this document
+[[window_rules]]  window placement rules           this document
+```
+
+There is no separate legacy visual namespace. Blur, opacity, radii, shadows,
+surface colors, typography, and shell component geometry belong only to
+`[theme.*]`.
+
+Representative core configuration:
+
 ```toml
-[appearance]
-glass = true
-blur_radius = 24.0
-glass_opacity = 0.82
-corner_radius = 14.0
-
-[appearance.shadow]
-enabled = true
-radius = 32.0
-offset_y = 8.0
-opacity = 0.28
-
-[appearance.active_border]
-style = "subtle"
-width = 2.0
-
 [animations]
 enabled = true
 reduced_motion = false
@@ -828,16 +987,27 @@ floating = true
 Command values are argument arrays, never shell command strings. Binding records
 use a normalized key chord, match mode, action, and optional argument. `keysym`
 matching is the default and follows the active XKB layout. `physical` matching
-uses XKB physical key names and is independent of the selected layout. The
+uses XKB physical key names and is independent of the selected layout.
-complete built-in set is listed in Section 14; when a user supplies a record for
+
-the same chord and match mode it replaces that default. A record with
+The complete built-in set is listed in Section 14; when a user supplies a record
+for the same chord and match mode it replaces that default. A record with
 `disabled = true` and no action explicitly unbinds the matching default.
+
 Duplicate normalized bindings, unknown actions, invalid arguments, and
 references to missing commands MUST fail validation. Every built-in binding
 MUST be expressible, replaceable, and removable through this schema.
 
-Unknown fields SHOULD warn. Invalid types, non-finite values, negative sizes,
+`ferese-config` MUST assemble all enabled namespace schemas and validate the
-and out-of-range opacity MUST fail validation.
+entire candidate configuration before applying any part of it. No companion
+component may maintain an independent competing copy of visual or shell
+configuration.
+
+The launcher and overview actions are desktop-tier defaults and MUST be installed
+only when their shell features are available. Their absence from a v0-only
+installation is not a validation error.
+
+Unknown fields SHOULD warn. Invalid types and invalid domain values MUST fail the
+owning schema's validation.
 
 Reload MUST debounce duplicate events, read the entire file, parse, validate,
 construct, and apply the difference as one transaction. Invalid input MUST NOT
@@ -861,8 +1031,7 @@ capabilities are:
 
 ```text
 effects
-overview-control
+shell-control
-global-metadata
 capture
 virtual-input
 ```
@@ -874,22 +1043,27 @@ client, and passes the client end only through an inherited descriptor such as
 arguments, environment secrets, or a discoverable private socket path.
 
 The compositor associates an explicit capability set with each private Wayland
-client and filters private globals and requests against that set. In particular,
+client and filters private globals and requests against that set.
-`ferese-effects-v1` requires `effects` and the private overview requests in
-`ferese-shell-v1` require `overview-control`. `ferese-shell` receives only the
-capabilities required by enabled shell features.
-`ferese-settings` receives `effects` when spawned as a trusted Ferese component;
-its configuration changes still use the normal validated IPC path.
 
-The private `capture` capability permits unattended capture only for a trusted
+`ferese-effects-v1` requires `effects`. `ferese-shell-v1` requires
-component. Public screencopy clients remain subject to the interactive or
+`shell-control`. `ferese-shell` receives only the capabilities required by
-configured capture policy and do not acquire this capability merely by binding
+enabled shell features. `ferese-settings` MAY receive `effects` when spawned as
-the public screencopy global.
+a trusted Ferese component; its configuration changes still use the normal
+validated configuration/IPC path.
+
+Public layer-shell does not require a private capability. The private `capture`
+capability permits unattended capture only for a trusted component. Public
+screencopy clients remain subject to interactive or configured capture policy
+and do not acquire `capture` merely by binding a public global.
 
 If a trusted component launches another privileged Ferese component, it MUST ask
 the compositor to create and pass a new capability-scoped private connection;
 it MUST NOT forward its own Wayland descriptor or capabilities.
 
+Ferese does not ship a polkit authentication agent in the initial desktop tier.
+Security-sensitive actions requiring system authentication MUST use an external
+agent until a separate authentication-agent security specification exists.
+
 ### 13.2 Framing
 
 IPC v0 uses unsigned 32-bit big-endian length-prefixed UTF-8 JSON:
@@ -940,12 +1114,13 @@ show-overview         hide-overview
 show-launcher         hide-launcher
 ```
 
-Enumerating all window titles or capturing pixels requires shell privilege.
+Managed-window enumeration, application identity metadata, shell activation,
+close, and overview-selection operations used by `ferese-shell` belong to the
+private `ferese-shell-v1` protocol rather than widening normal user-control IPC.
 
 Events include `window-opened`, `window-closed`, `window-focused`,
 `window-moved`, `workspace-changed`, `output-added`, `output-removed`,
-`config-changed`, and `config-error`. Payloads MUST omit titles and application
+`config-changed`, and `config-error`.
-IDs without shell privilege.
 
 Subscribers have bounded queues. The server MUST disconnect a subscriber whose
 queue overflows rather than block the compositor.
@@ -1028,7 +1203,7 @@ The target is sustained output refresh at 60 Hz on integrated graphics during
 ordinary use. Animation MUST also work at higher and variable refresh rates.
 
 Ferese SHOULD track frame, render, layout and blur duration; damaged pixels;
-missed presentation deadlines; surface and glass-region counts; and active
+missed presentation deadlines; surface, semantic-material, and blur-region counts; and active
 animations. Performance tracing MUST be optional. Suggested targets are
 `ferese::wayland`, `ferese::layout`, `ferese::render`, `ferese::input`,
 `ferese::ipc`, and `ferese::xwayland`.
@@ -1049,13 +1224,14 @@ stack cardinality, and do not duplicate or lose windows.
 Tests MUST cover defaults, partial files, unknown fields, invalid and non-finite
 values, duplicate key chords, unknown binding actions, missing command
 references, keysym versus physical matching, default unbinding, window-rule
-ordering, reload rollback, serialization, and atomic updates.
+ordering, theme/shell namespace ownership, reload rollback, serialization, and atomic updates.
 
 ### 17.3 IPC and security
 
 Tests MUST cover partial reads, multiple frames per read, oversized frames,
 unsupported versions, subscriptions, slow clients, peer-UID rejection, and
-denial of privileged commands without capability. Launch tests MUST prove that
+denial of privileged commands without capability, `shell-control` filtering, and
+public layer-shell remaining unprivileged. Launch tests MUST prove that
 children receive the public display and activation token but cannot inherit any
 private Wayland or privileged IPC descriptor.
 
@@ -1068,7 +1244,8 @@ visual geometry, configured client size, and committed client size. Nested
 integration tests SHOULD cover configure/commit behavior, inverse-transformed
 input during animation, clipboard, popups, drag-and-drop, focus, fullscreen,
 xdg-activation, output removal, private-client capability filtering, overview
-scene transitions, notification replacement/actions, and shell restart.
+scene transitions, top-bar reservation restart grace, application-identity association,
+DND behavior, notification replacement/actions, and shell restart.
 
 ## 18. Milestones
 
@@ -1148,14 +1325,16 @@ configured terminal launches without shell parsing; malformed clients do not
 affect availability; a 24-hour native-client soak has no compositor crash or
 unbounded resource growth; all Section 3.1 requirements pass.
 
-### M7: Glass materials
+### M7: Semantic surface materials
 
 Before choosing a shell toolkit, build a minimal `wayland-client` probe that
-creates a layer-shell surface and sets a semantic material through
+creates a layer-shell surface and requests `surface.panel` through
-`ferese-effects-v1`. Then implement capture, dual Kawase blur, tint, saturation,
+`ferese-effects-v1`. Then implement semantic role resolution for glass,
-noise, caching, and invalidation.
+translucent, and solid styles plus backdrop capture, blur, tint, saturation,
+optional noise, caching, and invalidation.
 
-Acceptance: the probe blurs only content behind its surface; backdrop changes
+Acceptance: the probe can switch among glass, translucent, and solid without
+changing geometry; glass blurs only content behind its surface; backdrop changes
 invalidate correctly; the effects global is visible only to a client with the
 `effects` capability; a public client cannot bind it; the demo meets its frame
 budget on the reference integrated GPU.
@@ -1165,17 +1344,21 @@ budget on the reference integrated GPU.
 First spike GPUI layer-surface creation, output discovery, focus, configure, and
 shutdown behavior. If the spike fails its lifecycle tests, use a thin native
 Wayland shell adapter or record a toolkit decision before proceeding. Implement
-the compositor overview scene, minimal `ferese-shell-v1` overview control,
+the compositor overview scene, minimal `ferese-shell-v1` control/metadata
-launcher UI, workspace strip, OSD, and the standard notifications D-Bus service.
+protocol, top bar, apps-only launcher UI, workspace UI, OSD, and the standard
+notifications D-Bus service.
 
-Acceptance: normal shell windows use layer-shell; `Super+Tab` controls overview;
+Acceptance: normal shell surfaces use public layer-shell; `Super+Tab` controls
-managed windows remain compositor-owned live scene nodes; selection follows
+overview; managed windows remain compositor-owned live scene nodes; selection
-visual geometry; notification replacement/actions work; shell restart does not
+follows visual geometry; the apps-only launcher uses application identity and
-disrupt windows; each trusted process receives only its assigned capabilities.
+XDG activation; DND and notification replacement/actions work; fullscreen hides
+the top bar without changing underlying layout geometry; shell restart preserves
+the top-bar reservation through its grace period; each trusted process receives
+only its assigned capabilities.
 
 ### M9: Settings and portals
 
-Build Appearance, Tiling, Shortcuts, Input, Workspaces, Displays, and About.
+Build Theme/Appearance, Tiling, Shortcuts, Input, Workspaces, Displays, and About.
 Implement the portal backend and PipeWire integration for screenshots and screen
 sharing.
 
@@ -1212,8 +1395,8 @@ round identically; terminal changes damage the correct regions; and all
 interaction remains responsive.
 
 M4 follows this nested slice immediately so frame pacing is validated on real
-hardware. Glass, GPUI, Settings, XWayland, notifications, portals, and theming
+hardware. Semantic materials, GPUI, Settings, XWayland, notifications, portals, and the
-MUST NOT delay it or the v0 core.
+graphical shell MUST NOT delay it or the v0 core.
 
 ## 20. Definition of v0
 
@@ -1234,7 +1417,8 @@ Ferese v0 is complete when a user can:
     restarts.
 
 The intended v0 result is a low-latency, independently usable tiling compositor.
-The desktop tier adds a coherent Ferese shell, glass, graphical settings,
+The desktop tier adds a coherent Ferese shell, semantic surface materials,
+graphical settings,
 portals, and X11 compatibility without redefining core correctness. Visual
 effects support hierarchy and usability; they do not replace correctness,
 responsiveness, or security.