Skip to content

Open source CapCut alternative.

TypeScript

docs: swift guide and the backlit icon treatment

David Le5744e2781792
diff --git a/docs/README.md b/docs/README.md
index 84285d86..c2c925c0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,6 +21,7 @@ Supported product and engineering guides live in `docs/guides/`. This list is th
- [Backend API Guide](guides/backend-apis.md) — the hosted routes the app and site call for model-backed work.
- [Frontend and Next.js Guidelines](guides/frontend-nextjs-guidelines.md) — route structure, server/client boundaries, styling, and data access in the site app.
+- [Backlit Icon](guides/backlit-icon.md) — the dark treatment that lights the donkey mark from behind: the layer stack, the tokens, and the rules that keep the mark clean.
**Operations**
@@ -30,7 +31,7 @@ Supported product and engineering guides live in `docs/guides/`. This list is th
**Working in this repo**
-- [Swift MVC Guide](guides/swift-mvc.md) — keeping product state, UI rendering, and AppKit orchestration separate in the app.
+- [Swift Guide](guides/swift.md) — the MVC split, language defaults, concurrency, SwiftUI, Mac platform behavior, data, and tests for the iOS and Mac apps.
- [Code Review Guide](guides/code-review.md) — what makes a change reviewable, and how we review.
- [Engineering Doc Style Guide](guides/eng-doc-style.md) — the required structure, sentence-level rules, and post-writing test for every doc here.
diff --git a/docs/guides/backlit-icon.md b/docs/guides/backlit-icon.md
new file mode 100644
index 00000000..bba47eb3
--- /dev/null
+++ b/docs/guides/backlit-icon.md
@@ -0,0 +1,216 @@
+# Backlit Icon
+
+The dark treatment for the donkey mark: the flat SVG appears lit from behind by
+three point sources. A duplicate silhouette sitting behind the mark generates
+all of the light; the mark on top stays exactly as drawn.
+
+**The one rule:** nothing composites above the icon. The icon renders at its
+own fills, with no filters and no tint, as the last layer drawn. If light
+appears on top of the mark, the stack is wrong.
+
+## The Layer Stack
+
+Bottom to top, in this order:
+
+```text
+1 backdrop near black
+2 bloom three wide blurred silhouettes
+3 halo three tight blurred silhouettes
+4 vignette radial darkening of the frame
+5 the icon untouched
+```
+
+The container supplies the backdrop and vignette; the icon element carries only
+the glow layers and the mark.
+
+## Files
+
+The treatment needs both files.
+
+| File | Role |
+| --- | --- |
+| `donkey-icon.svg` | The mark. Fully opaque, counters filled. The top layer. |
+| `donkey-silhouette.svg` | Outer contour only, no counters, `fill="currentColor"`. The glow source. |
+
+The mark cuts its counters — the eye, muzzle, and teeth — out of a single path
+by reverse winding. A glow layer built from the mark pours light through those
+cutouts and fills the interior with haze. The silhouette file keeps only the
+outer contour, so light escapes only past the outline.
+
+The same reasoning makes the icon opaque: a counter plate under the artwork
+keeps glow out of the interior even when a source sits directly behind the
+muzzle.
+
+## Tokens
+
+Every length is a multiple of the rendered icon size, so the treatment holds
+from 16px to print. `s` is the icon size; the mark is 264 × 318.
+
+| Token | Value |
+| --- | --- |
+| Halo blur | `0.030 × s` |
+| Bloom blur | `0.088 × s` |
+| Light colour | `#ffffff` |
+| Backdrop | `#000000` |
+| Counters | `#e9e7e0` |
+| Mark | `#051020` |
+| Vignette | `rgb(0 0 0 / 0.37)` at the corners, transparent at 25 percent radius |
+
+Three sources, each offset toward where its light sits.
+
+| Source | Offset x | Offset y | Halo opacity | Bloom opacity |
+| --- | --- | --- | --- | --- |
+| A, left | `-0.0297 × s` | `+0.0043 × s` | 0.80 | 0.192 |
+| B, above | `-0.0095 × s` | `-0.0285 × s` | 0.62 | 0.149 |
+| C, lower right | `+0.0190 × s` | `+0.0232 × s` | 0.35 | 0.084 |
+
+## Plain CSS
+
+```css
+.backlit {
+ --s: 32px;
+ --halo: calc(var(--s) * 0.030);
+ --bloom: calc(var(--s) * 0.088);
+ --light: #ffffff;
+
+ position: relative;
+ display: inline-block;
+ width: var(--s);
+ height: calc(var(--s) * 318 / 264); /* mark is 264 x 318 */
+ isolation: isolate;
+}
+
+.backlit__glow {
+ position: absolute;
+ inset: 0;
+ z-index: 0;
+ color: var(--light);
+ background: currentColor;
+ mask: url("donkey-silhouette.svg") center / contain no-repeat;
+ -webkit-mask: url("donkey-silhouette.svg") center / contain no-repeat;
+ pointer-events: none;
+ will-change: filter;
+}
+
+/* halo pass, tight */
+.backlit__glow--a { filter: blur(var(--halo)); opacity: 0.80; translate: calc(var(--s) * -0.0297) calc(var(--s) * 0.0043); }
+.backlit__glow--b { filter: blur(var(--halo)); opacity: 0.62; translate: calc(var(--s) * -0.0095) calc(var(--s) * -0.0285); }
+.backlit__glow--c { filter: blur(var(--halo)); opacity: 0.35; translate: calc(var(--s) * 0.0190) calc(var(--s) * 0.0232); }
+
+/* bloom pass, wide */
+.backlit__glow--a-wide { filter: blur(var(--bloom)); opacity: 0.192; translate: calc(var(--s) * -0.0297) calc(var(--s) * 0.0043); }
+.backlit__glow--b-wide { filter: blur(var(--bloom)); opacity: 0.149; translate: calc(var(--s) * -0.0095) calc(var(--s) * -0.0285); }
+.backlit__glow--c-wide { filter: blur(var(--bloom)); opacity: 0.084; translate: calc(var(--s) * 0.0190) calc(var(--s) * 0.0232); }
+
+.backlit__mark {
+ position: relative;
+ z-index: 1;
+ display: block;
+ width: 100%;
+ height: 100%;
+}
+```
+
+```html
+<span class="backlit" style="--s: 32px">
+ <span class="backlit__glow backlit__glow--a-wide"></span>
+ <span class="backlit__glow backlit__glow--b-wide"></span>
+ <span class="backlit__glow backlit__glow--c-wide"></span>
+ <span class="backlit__glow backlit__glow--a"></span>
+ <span class="backlit__glow backlit__glow--b"></span>
+ <span class="backlit__glow backlit__glow--c"></span>
+ <img class="backlit__mark" src="donkey-icon.svg" alt="Donkey" />
+</span>
+```
+
+The container it sits in supplies the backdrop and vignette.
+
+```css
+.backlit-stage {
+ background:
+ radial-gradient(circle at 50% 50%, transparent 25%, rgb(0 0 0 / 0.37) 100%),
+ #000000;
+}
+```
+
+## Tailwind
+
+Six absolutely positioned masked spans plus the mark. Arbitrary values carry
+the tokens.
+
+```jsx
+const GLOW = "absolute inset-0 bg-white pointer-events-none " +
+ "[mask:url(/donkey-silhouette.svg)_center/contain_no-repeat] " +
+ "[-webkit-mask:url(/donkey-silhouette.svg)_center/contain_no-repeat]";
+
+export function BacklitDonkey({ size = 32 }) {
+ const s = (k) => `${(size * k).toFixed(3)}px`;
+ const halo = s(0.030), bloom = s(0.088);
+ const sources = [
+ { x: -0.0297, y: 0.0043, halo: 0.80, bloom: 0.192 },
+ { x: -0.0095, y: -0.0285, halo: 0.62, bloom: 0.149 },
+ { x: 0.0190, y: 0.0232, halo: 0.35, bloom: 0.084 },
+ ];
+
+ return (
+ <span
+ className="relative inline-block isolate"
+ style={{ width: size, height: (size * 318) / 264 }}
+ >
+ {sources.map((src, i) => (
+ <span key={`w${i}`} className={GLOW}
+ style={{ filter: `blur(${bloom})`, opacity: src.bloom,
+ translate: `${s(src.x)} ${s(src.y)}` }} />
+ ))}
+ {sources.map((src, i) => (
+ <span key={`h${i}`} className={GLOW}
+ style={{ filter: `blur(${halo})`, opacity: src.halo,
+ translate: `${s(src.x)} ${s(src.y)}` }} />
+ ))}
+ <img src="/donkey-icon.svg" alt="Donkey"
+ className="relative block h-full w-full" />
+ </span>
+ );
+}
+```
+
+Stage wrapper.
+
+```jsx
+<div className="bg-black [background-image:radial-gradient(circle_at_50%_50%,transparent_25%,rgb(0_0_0/0.37)_100%)]">
+```
+
+## Rules
+
+Each of these is a failure mode already hit and fixed. Keep them.
+
+1. **The mark keeps its own colour.** No overlays, no filters on the icon
+ element, no light colour mixed in. The icon renders at its own fill and is
+ the last thing drawn.
+2. **Backdrop and vignette belong to the container.** They stop at the mark. A
+ vignette applied over the whole composite muddies the artwork.
+3. **Blur radii scale with icon size.** A fixed pixel blur looks right at one
+ size and turns to mush at 24px. Express every blur as a multiple of the
+ rendered size.
+4. **The counter colour is its own token.** Changing the backdrop leaves the
+ eye and teeth untouched; they follow the counter token.
+5. **Light travels a bounded distance from the outline.** Brightness falls off
+ with distance from the contour, which is what makes the composite read as a
+ backlight.
+6. **Watch the antialiased edge.** A near-white plate under an antialiased mark
+ produces a bright hairline around the whole outline. Keep the counter plate
+ inside the artwork edge.
+
+## Other Marks
+
+Replace both SVGs: the silhouette is the outer contour with counters removed,
+and the icon is opaque. Every token is relative to size and every offset is
+relative to the mark centre, so the rest carries over unchanged.
+
+## Scale Guidance
+
+| Context | `--s` | Note |
+| --- | --- | --- |
+| Toolbar | 16 to 24px | Drop bloom opacity by half; the wide pass mostly disappears anyway |
+| Sidebar or nav | 32 to 48px | Values as specified |
+| Hero or splash | 128px and up | Consider raising bloom; the frame can carry more spread |
diff --git a/docs/guides/code-review.md b/docs/guides/code-review.md
index c7ba5347..48d0e7ec 100644
--- a/docs/guides/code-review.md
+++ b/docs/guides/code-review.md
@@ -42,7 +42,7 @@ Pay it only when it buys something.
five.
Indirection that maps to a real boundary is good: the Swift MVC split
-(`docs/guides/swift-mvc.md`) exists for a reason. The tax is forwarding
+(`docs/guides/swift.md`) exists for a reason. The tax is forwarding
layers that exist for their own sake.
## Design Simplicity
@@ -77,7 +77,7 @@ layers that exist for their own sake.
turn through an LLM or a typed model boundary, then match on structured
output only.
2. **Keep the Swift MVC boundaries intact.** Views render and emit intents,
- models own state, controllers own AppKit. See `docs/guides/swift-mvc.md`.
+ models own state, controllers own AppKit. See `docs/guides/swift.md`.
3. **Follow the site guides.** For `site` UI,
`docs/guides/frontend-nextjs-guidelines.md`: server components by default,
no `fetch` from components, no `any`. For database work,
diff --git a/docs/guides/frontend-nextjs-guidelines.md b/docs/guides/frontend-nextjs-guidelines.md
index d1e058ef..39552c5f 100644
--- a/docs/guides/frontend-nextjs-guidelines.md
+++ b/docs/guides/frontend-nextjs-guidelines.md
@@ -107,6 +107,9 @@ back open, like a dropdown, closes in a `useLayoutEffect` cleanup.
- Compose conditional classes with the `cn` helper from `@/lib/utils`.
- Prefer existing icon components for buttons and compact actions when an icon
fits the control.
+- On dark surfaces, render the donkey mark with the treatment in the
+ [Backlit Icon guide](backlit-icon.md). Its layer stack, tokens, and rules are
+ the supported values; the mark itself always renders untouched on top.
- Keep controls at stable dimensions so hover states, icons, labels, and
loading states do not shift layout.
- Keep cards for repeated items, modals, and genuinely framed content. Avoid
diff --git a/docs/guides/swift-mvc.md b/docs/guides/swift-mvc.md
deleted file mode 100644
index d9c975c3..00000000
--- a/docs/guides/swift-mvc.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# Swift MVC Guide
-
-Donkey Swift code keeps product state, UI rendering, and AppKit orchestration
-separate, so the app's UI stays easy to change without coupling it to runtime
-work. Views render and emit typed intents; models own state;
-controllers own AppKit.
-
-**The one rule:** `DonkeyUI` never imports `DonkeyRuntime`.
-Runtime work reaches a view only as data its model passes in, never through
-view internals.
-
-## Pattern
-
-- Model owns observable product state and intent handling.
-- View renders state and emits typed intents.
-- Controller owns AppKit lifecycle, windows, timers, geometry, and side effects.
-- App entry wires the first model and controller, then gets out of the way.
-
-## Technical Guidelines
-
-- Keep SwiftUI views value-like: pass state in, pass typed intent sinks out,
- and avoid timers, global mouse reads, model providers, or window management
- inside views.
-- Keep models on `@MainActor` when they publish UI state. Models may depend on
- narrow provider protocols, but not on AppKit windows or timers.
-- Keep controllers on `@MainActor` when they touch AppKit. Controllers may read
- screen and event geometry, monitor double-Command activation, own `NSPanel`,
- and translate geometry into model state.
-- Keep app entry files small: `@main`, delegate adaptation, and little else.
-- Prefer target-level separation for reusable UI and runtime work: `DonkeyUI`
- holds views, `DonkeyRuntime` holds the engine supervisor, bundled tools, and
- the recorder.
-- Name files after their MVC role when a feature grows past one screen:
- `FeatureModel.swift`, `FeatureRootView.swift`, `FeatureController.swift`.
-
-## Current Donkey Shape
-
-Screen recording follows this split: `ScreenRecorder` and its destination types
-hold the capture state; `RecordingControlBarView` renders it; the controllers own
-AppKit-only work such as the control bar panel, the region and window pickers, and
-screen positioning; `DonkeyAppDelegate` bootstraps the feature and the menu bar
-without owning product behavior. The pointer is captured as data: the stream draws
-no cursor, and `CursorTrackRecorder` samples where it went into a `.cursor.json`
-beside the movie for an editor to draw or follow.
-
-## Review Checklist
-
-- A SwiftUI view does not call `NSEvent.mouseLocation`, create an `NSPanel`,
- start a `Timer`, or import `DonkeyRuntime`.
-- A model does not import `DonkeyUI`.
-- A model does not know about frames, screens, windows, or animation timing.
-- A controller does not store business text or decide model-provider behavior
- beyond presenting existing model state.
-- New product behavior adds or extends a guide in `docs/guides/`.
diff --git a/docs/guides/swift.md b/docs/guides/swift.md
new file mode 100644
index 00000000..a432afd7
--- /dev/null
+++ b/docs/guides/swift.md
@@ -0,0 +1,126 @@
+# Swift Guide
+
+How to write Swift for the iOS and Mac apps in this repo: the MVC split,
+language defaults, concurrency, SwiftUI, platform behavior, data, and tests.
+
+**The one rule:** `DonkeyUI` never imports `DonkeyRuntime`. Runtime work
+reaches a view only as data its model passes in, never through view internals.
+
+## The MVC Split
+
+Product state, UI rendering, and AppKit orchestration stay separate, so the
+app's UI stays easy to change without coupling it to runtime work.
+
+- Model owns observable product state and intent handling.
+- View renders state and emits typed intents.
+- Controller owns AppKit lifecycle, windows, timers, geometry, and side effects.
+- App entry wires the first model and controller, then gets out of the way:
+ `@main`, delegate adaptation, and little else.
+
+Prefer target-level separation for reusable UI and runtime work: `DonkeyUI`
+holds views, `DonkeyRuntime` holds the engine supervisor, bundled tools, and
+the recorder. Name files after their MVC role when a feature grows past one
+screen: `FeatureModel.swift`, `FeatureRootView.swift`,
+`FeatureController.swift`.
+
+Screen recording follows this split: the recorder and its destination types
+hold the capture state; the control bar view renders it; controllers own the
+AppKit-only work such as the control bar panel, the region and window pickers,
+and screen positioning; the app delegate bootstraps the feature and the menu
+bar without owning product behavior. The pointer is captured as data: the
+stream draws no cursor, and a track recorder samples where it went into a
+`.cursor.json` beside the movie for an editor to draw or follow.
+
+## Language
+
+- Model data as structs and enums. Reserve classes for identity, shared mutable
+ state, and framework requirements.
+- Make illegal states unrepresentable. An enum with associated values beats a
+ struct of optionals that are never both nil: `case loading`,
+ `case loaded(Data)`, `case failed(Error)`.
+- Handle optionals honestly: `guard let` for early exit, `if let` for
+ branching, `??` for defaults. Force-unwrap only where nil is a programmer
+ error worth crashing on, such as a bundled resource.
+- Errors are typed control flow: `throws` and `do/catch`, with a small error
+ enum per subsystem.
+- `let` until the compiler demands `var`.
+- Define a protocol where a seam needs testing or multiple conformers exist.
+ Write `some Protocol` by default; `any Protocol` only for heterogeneous
+ values. Models may depend on narrow provider protocols.
+- Name methods so call sites read as phrases: `list.insert(element, at: index)`.
+
+## Concurrency
+
+- Stay on the main actor and leave it deliberately. Projects set default actor
+ isolation to the main actor, so views, models, and helpers agree by
+ construction — models publishing UI state and controllers touching AppKit
+ are covered with zero annotations.
+- Mark CPU-heavy async work `@concurrent` to move it off the main actor:
+ parsing, image work, encoding.
+- Use an actor for mutable state hit from many tasks: caches, download
+ managers, database handles.
+- Prefer structured work — `async let`, task groups, and `.task {}` on views —
+ so cancellation propagates. Long loops call `Task.checkCancellation()`.
+- New event streams use AsyncSequence.
+
+## SwiftUI
+
+- Keep views value-like: pass state in, pass typed intent sinks out. Timers,
+ global mouse reads, model providers, and window management belong in
+ controllers.
+- State lives in `@Observable` classes. The view that creates a model owns it
+ with `@State`; app-wide services inject with `@Environment`; write access to
+ someone else's state passes as `@Binding` or `@Bindable`.
+- Models import Foundation only. A SwiftUI or AppKit import in a model means
+ view or controller concerns leaked in, and it costs headless testability.
+- Navigation: `NavigationStack` with typed path values for drill-down;
+ `NavigationSplitView` for sidebar layouts, which collapse to a stack on
+ iPhone.
+- When SwiftUI runs out — heavy custom text, camera or Metal surfaces — wrap
+ the smallest possible AppKit or UIKit view in a representable and keep the
+ SwiftUI shell.
+
+## The Mac Is Its Own Platform
+
+Share models and feature logic across platforms; split views where behavior
+diverges. Keep `#if os(macOS)` out of feature logic — a shared model driving a
+Mac view and an iOS view beats one view full of conditionals.
+
+Mac users expect:
+
+- Every meaningful action in the menu bar with a keyboard shortcut, via
+ `.commands`.
+- The standard scenes: `Settings` for preferences, `Window` for singletons,
+ `MenuBarExtra` for status-bar presence.
+- Keyboard-first flows: focus, `.keyboardShortcut`, arrow keys through
+ `onMoveCommand`, Escape to cancel.
+- Desktop density: sidebars, tables, inspectors, hover states, drag and drop
+ through Transferable.
+
+## Data
+
+- Small preferences use `@AppStorage`; secrets go in the Keychain.
+- Keep any store behind a small repository type the rest of the app talks to.
+ Feature-layer models stay plain structs; persistence types stay at the edge.
+- Network with URLSession, async/await, and Codable. Decode at the boundary
+ into domain types; wire formats never leak past the client layer.
+
+## Tests
+
+- Write new tests with Swift Testing: `@Test` functions, `#expect` for soft
+ failures, `#require` to abort, arguments for parameterized cases.
+- Test models and services headlessly — the payoff of keeping UI frameworks
+ out of them. UI correctness comes from previews plus a thin set of UI tests
+ on critical flows.
+- Tests run in parallel by default. When that surfaces shared state, fix the
+ state.
+
+## Review Checklist
+
+- A SwiftUI view does not call `NSEvent.mouseLocation`, create an `NSPanel`,
+ start a `Timer`, or import `DonkeyRuntime`.
+- A model does not import `DonkeyUI`.
+- A model does not know about frames, screens, windows, or animation timing.
+- A controller does not store business text or decide model-provider behavior
+ beyond presenting existing model state.
+- New product behavior adds or extends a guide in `docs/guides/`.