max / alloy

10.1 KB · 107 lines History Blame Raw

1	# Hardware target: Framework Laptop 12
2
3	The Framework 12 is the first hardware target Alloy is being built against on real metal. This document records what the device is, how the 2-in-1 form factor bends the stack, and every hardware-adjacent decision Alloy has to make earlier than it otherwise would. Companion to [STACK.md](STACK.md).
4
5	Per-device docs are the pattern: this is `HARDWARE-FW12.md`. If Alloy is later validated against a Framework 13, a ThinkPad, or a Star Labs machine, each gets its own file. Cross-device concerns get promoted to a shared doc only when a second device demands it.
6
7	## Why this device, why now
8
9	The Framework 12 is a 12.2" convertible (360-degree hinge, touchscreen, optional stylus) with the standard Framework expansion-card mainboard, x86_64 Intel silicon, and full Linux firmware support via LVFS. It is repairable, has good Linux upstream driver coverage in current Fedora kernels, and Framework itself validates Fedora as a supported distribution on the device.
10
11	It is also the most demanding first target Alloy could pick: convertible hardware forces the project to answer questions a clamshell laptop lets it defer for a year (touch, on-screen keyboard, rotation, tablet-mode input gating). Answering these once, up front, is cheaper than answering them after the design system has already ossified around a keyboard-only assumption.
12
13	## Alloy's stance on the 2-in-1 form factor
14
15	Alloy stays keyboard-first, and the FW12 is supported as a laptop. The fold-to-notes tablet gesture (a stylus notes canvas on hinge fold) is shelved: it needs a stylus GUI, which clashes with the TUI-first direction. The "Fold-to-notes" section below is that shelved design, and it revives only if a tablet UX returns.
16
17	The manifesto commits Alloy to a keyboard-driven tiling environment. A 2-in-1 does not change that thesis. In clamshell use:
18
19	- Clamshell mode is the entire Alloy experience. Sway and the full terminal-first stack, unchanged.
20	- Touch and stylus in clamshell mode are pointer input, nothing more. Tap to focus a window, drag to scroll, stylus behaves as a pointer. Sway and libinput already do this without Alloy code.
21	- Folding the screen back does nothing special; the session stays as-is.
22
23	This stance is deliberate. Building a general-purpose touch UI is a years-shaped project (Phosh, GNOME Shell-for-mobile, Plasma Mobile). Alloy is a months-shaped project, and a TUI-first one; a custom tablet shell is out of scope.
24
25	## Display
26
27	- Native panel: 12.2" 1920x1200 (16:10), matte, IPS-class, ~185 PPI. Sits in the awkward middle where 1.0x is too small and 2.0x is too big.
28	- Alloy default scale: 1.25x fractional under sway (`output eDP-1 scale 1.25`). Not shipped as a system file naming this laptop: the installer reads the panel's size out of its EDID and writes the directive to `~/.config/sway/config.d/50-display.conf`, from the same generator `alloy display` uses, so the value is the machine's own and its owner can change it with one keypress. This panel is the measurement the rule is anchored on — ~185 PPI takes 1.25, which is `PPI_PER_SCALE` in `crates/alloy/src/display.rs`. sway handles the compositor side; terminal apps scale with the compositor, so there is no per-app fractional-scale work. Verify glyph crispness at v0 sanity check.
29	- Contrast/color: validate the DESIGN-LANGUAGE.md dark-mode L stops on this panel specifically (currently deferred in `todo.md`). Matte 400-nit IPS is roughly the panel class most Alloy users are likely to have; if the tokens miss here, they miss for the base audience.
30
31	Rejected: 1.0x default (glyphs too small at arm's length on 12.2"), 1.5x default (wastes usable columns in a scrollable-tiling model where horizontal density matters).
32
33	## Touch and stylus as pointer
34
35	Touch and stylus both work out of the box on Wayland via libinput. Sway routes them to clients as pointer events. No Alloy code required for the base case.
36
37	- Touch: tap to focus, drag to scroll. Sway's built-in touch handling covers workspace-switch gestures.
38	- Stylus: USI 2.0 supported by the FW12 panel. Routes through libinput's tablet-tool path as pointer input. Pressure and tilt are available to any client that asks; Alloy's own widgets do not consume them.
39	- Palm rejection: handled by libinput. No Alloy work.
40
41	`alloy_tui` does not ship a Touch/Pointer input-mode split; a TUI is keyboard-first by nature and terminal apps take pointer input only incidentally. If touch ergonomics ever matter, revisit, but not preemptively.
42
43	## Fold-to-notes (SHELVED)
44
45	Shelved: TUI-first clashes with a stylus GUI. The `alloy-hinged` daemon, the notes workspace and the Rnote pick below are not on the roadmap and revive only if a tablet UX returns. The niri IPC calls below are written against a compositor Alloy does not ship.
46
47	The kernel exposes hinge state via `SW_TABLET_MODE` on Framework's ACPI/EC path. The shelved design consumed it for one purpose: switching to a dedicated notes workspace on fold, and back on unfold.
48
49	Behavior:
50
51	- On fold: `niri msg action focus-workspace notes`. If the notes app is not already running on that workspace, spawn it. Fullscreen it.
52	- On unfold: `niri msg action focus-workspace previous` (or the named workspace the user was on before).
53	- Notes app keeps running in the background between folds. State preserved by the app's own autosave, not by Alloy.
54
55	Notes app pick: Rnote. Rust, GTK4, purpose-built for stylus free-hand notes. Ships in Fedora repos. Infinite canvas, pressure and tilt, eraser, autosave, export to PDF/SVG. Fits Alloy's Rust-forward posture and the workflow exactly.
56
57	Rejected: Xournal++ (mature but heavier and more PDF-annotation-shaped than free-writing-shaped), a custom egui note app (real design-system win but a marquee-app-sized project for a feature Rnote already solves well; revisit only if Rnote hits a wall).
58
59	Daemon. Small user-session Rust binary, single-purpose. Reads `SW_TABLET_MODE` transitions (via evdev or `iio-sensor-proxy`) and issues Niri IPC commands. Approximately 100 LOC. Ships as a systemd user service. Named `alloy-hinged` (working name).
60
61	Not a general "device-adaptation layer"; deliberately single-purpose. If rotation, OSK, ambient light, or lid handling ever become real needs, they get their own daemons or get absorbed here with intent; not preemptively scaffolded.
62
63	Physical keyboard and trackpad when folded. The kernel usually suppresses these on `SW_TABLET_MODE` transitions, but behavior varies by device. Verify on the FW12 specifically. If it doesn't, one extra libinput toggle in `alloy-hinged` on fold/unfold covers it.
64
65	Auto-rotation: deferred. Rnote's infinite canvas makes landscape fine; no portrait requirement. If a user asks for it later, `iio-sensor-proxy` + a few lines in `alloy-hinged` adds it.
66
67	## Fingerprint reader
68
69	Framework 12 ships a fingerprint reader on the power button. Upstream Linux support is via `libfprint`; enrollment through `fprintd`. Fedora Silverblue includes the stack.
70
71	- Alloy configures PAM to allow fingerprint wherever the system asks who you are: at the lockscreen, and at the polkit prompt, which is the one `run0` and the console's writing views both raise. The file that matters for the second is `/etc/pam.d/polkit-1`, not `/etc/pam.d/sudo` — Alloy documents `run0` rather than `sudo` (wiki note `alloy-privilege`), so a fingerprint stack that only covered sudo would cover nothing a user is told to type.
72	- Fingerprint unlock wires through swaylock's PAM stack. No Alloy code beyond PAM config.
73
74	## Firmware (fwupd / LVFS)
75
76	Framework publishes firmware via LVFS. Fedora Silverblue ships `fwupd` and enables LVFS by default.
77
78	Alloy's contribution: nothing. There is no first-boot firmware check and no prompt. Alloy publishes no image, so the ISO is built on the installer's own machine shortly before it is used, and firmware current at build time is still current at first boot. A first-boot prompt is also a check nobody asked for, which is what the update position in [STACK.md](STACK.md) declines to do.
79
80	Someone who wants to know runs `fwupdmgr get-devices` and `fwupdmgr update`, which work and need nothing from Alloy. The assumption this rests on, and it is an assumption rather than a guarantee: anyone building their own ISO is savvy enough to update firmware when they care to.
81
82	## Power management
83
84	- Suspend model: s2idle (Modern Standby / S0ix) only. S3 is not available on the platform. Idle drain during s2idle has historically been a Linux pain point on Intel; Fedora's `power-profiles-daemon` + tuned defaults are the current best baseline. Track s2idle drain as an open concern; do not layer TLP on top of ppd.
85	- Profiles: default to `balanced`. Expose profile switching via the `alloy` console (an `alloy power` verb, or within `alloy display`), not a dedicated power tool.
86	- Lid close: suspend, standard.
87
88	## Wi-Fi, Bluetooth, webcam, audio
89
90	All expected to work with in-tree Fedora kernel drivers. No Alloy-specific handling planned. If a specific chipset in the FW12 turns out to need out-of-tree firmware, add a note here and to the image-composition manifest.
91
92	Physical camera and microphone switches are on the chassis (Framework standard). Alloy does not need to plumb software mute: the hardware switch is authoritative.
93
94	## Expansion cards
95
96	Framework's expansion-card system is a hardware concern, not a software one, but Alloy should:
97
98	- Not assume a fixed USB-C port layout. UI that talks about "the left port" is wrong on a Framework.
99	- Handle hot-plug of storage expansion cards cleanly (this is a udev + userspace-mount concern, mostly not Alloy's).
100
101	## Open questions
102
103	- [ ] fprintd unlock through swaylock's PAM stack on the FW12: enroll, then verify unlock at swaylock and at a `run0` prompt (polkit's PAM stack, via `pkttyagent`).
104	- [ ] Fractional-scale validation at 1.25x on this panel under sway: do terminal glyph metrics stay crisp?
105	- [ ] s2idle drain measurement on FW12 running the Alloy image, baseline vs. tuned. If drain is bad enough to matter, revisit whether Alloy ships any power tweaks or leaves it to Fedora defaults.
106	- [ ] (shelved) The `alloy-hinged` fold-to-notes questions (keyboard/trackpad suppression on `SW_TABLET_MODE`, Rnote fullscreen behavior) revive only if the tablet flow comes back.
107