Open source CapCut alternative.
TypeScript
docs: swift guide and the backlit icon treatment
David Le5744e2781792
diff --git a/docs/README.md b/docs/README.mdindex 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.mdnew file mode 100644index 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.mdindex 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 forwardinglayers 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 structuredoutput 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.mdindex 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 iconfits 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, andloading states do not shift layout.- Keep cards for repeated items, modals, and genuinely framed content. Avoiddiff --git a/docs/guides/swift-mvc.md b/docs/guides/swift-mvc.mddeleted file mode 100644index 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.mdnew file mode 100644index 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/`.