extract music player deps - souveraine-player is its own crate now

docs/tasks/souveraine-lock-primitives.md

@@ -0,0 +1,191 @@
+---
+task_id: souveraine-lock-primitives-001
+title: "Souveraine-owned AGPL lock primitives — cut the cord from ii by rewriting"
+status: pending
+priority: high
+phase: build
+created: 2026-07-18
+references: docs/tasks/qs-souveraine-composer.md, docs/DECISIONS.md, ~/Projects/MAKE_PROPER_LICENSES_FOR_ALL_PROJECTS.md, surfaces/quickshell/modules/ii/lock/TouchLockSurface.qml, surfaces/quickshell/modules/souveraine/lock/
+---
+
+# Souveraine-owned AGPL lock primitives
+
+## The end goal (build THIS, not an increment)
+
+A fully Souveraine-owned, fully AGPL lock surface. Zero ii-derived files in
+the lock dependency graph. Every primitive the lock uses is original
+Souveraine-authored QML, licensed AGPLv3, designed to behave how *we* want
+— not a copy of ii.
+
+There is no v1/v2 here. We do not vendor ii files. We do not borrow ii
+widgets as a bridge. We accept that the lock may not compile, or may be
+missing a subcomponent, while the owned primitives are built. That is
+preferable to a single borrowed-widget compromise. See the cord-cut rule in
+`docs/DECISIONS.md` ("Shell = own config") and
+`docs/tasks/qs-souveraine-composer.md`.
+
+## Why rewrite, not vendor
+
+Vendoring an ii file inherits GPLv3 — we can never make it ours by
+relabeling. The licensing master doc governs the boundary: original
+Souveraine files get AGPL headers + Casey as copyright holder; genuinely
+inherited GPLv3 files keep their headers. Because we choose to author
+rather than inherit, every lock primitive will be original AGPL, and the
+lock surface conveys cleanly under our license. ii is behavioral reference
+only — read how it behaves, write our own implementation. Do not copy.
+
+## What the lock surface currently depends on
+
+Direct external symbols referenced by the lock files (verified by grep,
+2026-07-18):
+
+| Symbol | Used by | What it is |
+|--------|---------|------------|
+| `RippleButton` | `TouchLockSurface.qml` (KeypadButton, UtilityButton inline components) | Pressable button with material-ripple feedback. Transitive ii dep: `MaterialShape`. |
+| `StyledText` | `TouchLockSurface.qml` (dots hint, keypad glyphs, hint labels) | Themed text bound to `Appearance` colors/fonts. |
+| `MaterialSymbol` | `TouchLockSurface.qml` (icons: backspace, arrow, power, reboot) | Material Symbols icon glyph. |
+| `ErrorShakeAnimation` | `TouchLockSurface.qml` (wrong-PIN shake on `dotsArea`) | Frame-driven horizontal shake animation. |
+| `Appearance` (singleton) | `TouchLockSurface.qml` (15×), `LockScreen.qml` (1×). The host + cards use raw literals instead — evidence for the palette work below. | Colors (`colOnLayer1`, `colError`, `colSubtext`, `colOnSurfaceVariant`, `colOnPrimary`) + font pixel sizes. |
+| `ColorUtils` | `TouchLockSurface.qml` | `transparentize()`. |
+| `Translation` | `TouchLockSurface.qml` | `tr()` i18n. |
+| `MaterialShape` | transitive (used by ii's RippleButton) | Material-style rounded/shape background. First-class rewrite target since our RippleButton needs it. |
+
+Everything else in the lock files is QtQuick/QtQuick.Layouts/Quickshell
+(primitives we keep) or Souveraine-owned already (`GlobalStates`,
+`LockContext`, `Config`, `LockContentPolicy`, `Ai`, `Battery`,
+`LockSurfaceHost`, `LockMediaCard`, `LockAgentCard`).
+
+## What to build (the primitive set)
+
+All under a Souveraine-owned path — propose
+`surfaces/quickshell/modules/souveraine/widgets/` — each file original AGPL,
+Casey as copyright holder, designed from the lock's needs with ii as
+behavioral reference only.
+
+### Tier 0 — theme singletons (these are not optional; everything below keys off them)
+
+- **`Appearance`** — colors + font scale. This is the single source of truth
+  every styled component reads. Decide the Souveraine lock palette here
+  (replacing the scattered literals `#d9ffffff`, `#e6ffffff`, `#1c1b20`,
+  `#b3181b20`, `#22000000`, `#33ffffff`, `#55ffffff` currently hand-rolled
+  across the three lock cards). One palette, named tokens.
+- **`ColorUtils`** — at minimum `transparentize(color, amount)`.
+- **`Translation`** — `tr()` passthrough to whatever i18n we standardize on.
+
+### Tier 1 — visual primitives
+
+- **`StyledText`** — text bound to Appearance tokens; the type every label
+  uses.
+- **`MaterialSymbol`** — icon glyph renderer.
+- **`MaterialShape`** — material background shape (rounded rect minimum;
+  designed so `RippleButton` can compose it).
+- **`ErrorShakeAnimation`** — horizontal shake with the *midpoint-crossing
+  termination* rule (stop when the oscillation would cross the rest point,
+  not on a fixed timer — Phosh's `shake_entry` model, frame-clock driven).
+
+### Tier 2 — composite primitives (compose Tier 1)
+
+- **`RippleButton`** — the pressable button. Ripple feedback baked in from
+  day one (this is one of the "minor details" Casey wants to tweak — build
+  it ours, tunable). Properties the lock uses today: `contentItem`,
+  `colBackground`, `buttonRadius`, `toggled`, `enabled`, signals
+  `clicked`/`pressAndHold`.
+
+### Tier 3 — lock-surface components (built on the owned primitives)
+
+These replace the inline blocks in `TouchLockSurface.qml`:
+
+- **`AmbientCard`** — the shared bordered rounded-rect card both
+  `LockMediaCard` and `LockAgentCard` currently hand-roll with different
+  radii/alphas. One primitive, one palette.
+- **`PinDots`** — the entered-PIN dots row + empty-state hint, with
+  `ErrorShakeAnimation` wired in.
+- **`LockKeypad`** — the 3×3 + 0/backspace/confirm grid, built from our
+  `RippleButton`.
+- **`LockUtilityRow`** — power / battery / reboot, from our `RippleButton`.
+- **`LockReveal`** — the glance↔PIN stage controller. Owns the reveal
+  intent (`reveal()`, `retreat()`) so every input path (swipe, tap-hint,
+  hardware key, future double-tap-clock) funnels through one transition
+  instead of each re-implementing threshold logic. Replaces the inline
+  `pressY`/threshold/retreat-timer block in `TouchLockSurface.qml`.
+
+### The result
+
+`TouchLockSurface.qml` shrinks to ~layout + intent wiring (target ~60–80
+lines), built entirely on Souveraine-owned AGPL QML. The lock dep graph has
+zero ii-derived files.
+
+## How to build it (approach, not steps)
+
+1. **Tier 0 first.** `Appearance`/`ColorUtils`/`Translation` — nothing else
+   compiles without them. Define the Souveraine lock palette here as named
+   tokens; retire the scattered literals.
+2. **Tier 1 next**, in dependency order: `StyledText` (needs Appearance),
+   `MaterialSymbol`, `MaterialShape`, then `ErrorShakeAnimation`
+   (standalone).
+3. **Tier 2:** `RippleButton` (composes `MaterialShape`).
+4. **Tier 3:** `AmbientCard`, `PinDots`, `LockKeypad`, `LockUtilityRow`,
+   `LockReveal` — built on Tiers 0–2.
+5. **Rewire `TouchLockSurface`** and the two cards to consume the owned
+   primitives, removing every ii import.
+
+Each file lands with an AGPLv3 header and Casey as copyright holder.
+Behavioral reference from ii is fine (read how ii's `RippleButton` feels,
+what properties it exposes); copying is not.
+
+## ii reference access (behavioral, read-only)
+
+ii's widget sources are NOT in this repo. They live on the phone at
+`/home/casey/.config/quickshell/ii/modules/common/widgets/` (RippleButton,
+StyledText, MaterialSymbol, MaterialShape, ErrorShakeAnimation, etc.) and
+on the laptop at `~/.config/quickshell/ii/`. SSH: `ssh pixel`. Read them to
+understand behavior and the property contract the lock code expects — do
+not copy. Write fresh AGPL implementations.
+
+Phosh's lockscreen source is also on the phone at `~/build/phosh/src/`
+(`lockscreen.c`, `ui/lockscreen.ui`) — useful behavioral reference for the
+swipe-capture model (deck/carousel, rounded-progress page gating) and the
+shake midpoint-crossing termination. Do not port; implement in QML.
+
+## Manifest + composer wiring
+
+Every new Souveraine-owned file needs a line in
+`surfaces/quickshell/deploy.sh` `MANIFEST` (the composer only ships files
+in the manifest — a missing line means "is not a type" at load). As files
+are written, add manifest lines pointing them into the `souveraine/`
+composed config. Borrowed ii widget dirs stay borrowed for the rest of the
+shell until their own cord-cut; only the lock's deps are cut here.
+
+## License headers
+
+Per `~/Projects/MAKE_PROPER_LICENSES_FOR_ALL_PROJECTS.md`:
+
+- Every file written here: AGPLv3 header, Casey Tunturi as copyright holder.
+- Do NOT put inherited GPLv3 headers on these — they are original work.
+- Mixed tree is honest: the lock dep graph is all-original AGPL after this
+  task; other parts of the shell may still carry inherited GPLv3 until their
+  own rewrite.
+
+## Non-goals / out of scope for this task
+
+- Rewriting non-lock widgets (dock, sidebar, overview, etc.) — separate
+  cord-cuts, separate tasks.
+- Changing lock *behavior* beyond what the primitive rewrite naturally
+  enables. Feature additions (clock double-tap, new gesture paths, peek
+  mode) are follow-on work on top of the owned primitives, not part of
+  getting the substrate owned.
+- Touching sessiond (Rust) — it is already Souveraine-owned and unaffected.
+
+## Done when
+
+- [ ] Tier 0–2 primitives exist as original AGPL files under
+      `modules/souveraine/widgets/` (or agreed path), each with AGPL header.
+- [ ] Tier 3 lock components exist, built on the owned primitives.
+- [ ] `TouchLockSurface.qml` + both lock cards import only Souveraine-owned
+      + Qt/Quickshell modules — zero `qs.modules.common.widgets`
+      ii-borrowed imports in the lock graph.
+- [ ] The lock surface dep graph contains no ii-derived files (grep
+      verifiable).
+- [ ] Manifest lines added; `deploy.sh --phone` ships and the lock runs.
+- [ ] Cord-cut ledger updated (this file's "Done when", or a dedicated
+      ledger) recording which borrowed dirs remain.