@topy-ai/maggie 0.8.6 → 0.8.8

package/references/redesign-audit.md

@@ -0,0 +1,144 @@
+# Redesign audit (existing sites)
+
+A diagnostic checklist for upgrading an **existing** site or app to premium quality:
+find the generic AI-design patterns, weak states, and sloppy code, then fix them
+**in place** without breaking functionality or migrating frameworks. Used by the `maggie-design` skill - run the
+audit to decide *what* to change, then apply the changes through maggie-design's
+`in-place` / `section` / `verify` flow (small, reviewable, evidence-backed edits),
+never a rewrite.
+
+Concrete values (fonts, dark colours, spacing, type scale, radius, icons, motion)
+come from [landing-page visual defaults](landing-page-visual-defaults.md); they are
+**defaults** that the project's own DESIGN.md/tokens override. Never invent a value
+that is in neither place - ask. Adapted from `elayadesign/redesign-skill`
+`redesign-existing-projects` (MIT; from `Leonxlnx/taste-skill`); see Credits.
+
+## How to run it
+
+1. **Scan** - read the codebase; identify framework, styling method (Tailwind v3/v4,
+   vanilla CSS, styled-components, CSS modules), and the current patterns.
+2. **Diagnose** - go through the audit below; list every generic pattern, weak
+   point, and missing state. **Report before fixing; let the user veto items.**
+3. **Fix** - apply targeted upgrades inside the existing stack, in the Fix-priority
+   order, through maggie-design (test after each; keep diffs reviewable).
+
+## Audit
+
+### Typography
+Browser-default or Inter/Roboto/Arial/Open Sans/Helvetica fonts; two typefaces on
+one site; any italics; ultra-bold (800/900); only 400+700 in use (add 500/600);
+headlines lacking presence (more display size, tighter tracking); body wider than
+~65 characters; proportional numerals in data UI (use `tabular-nums`); missing
+letter-spacing (negative on big headers, positive on small caps); all-caps
+subheaders everywhere; orphaned words (`text-wrap: balance`/`pretty`); hyphens in
+copy; off-scale font sizes (snap to the type scale, closest step below); off-scale
+button type (main `text-base` semibold, header `text-sm` semibold).
+
+### Colour and surfaces
+Backgrounds outside the approved dark palette (snap to it; not `#0a0a0a`/`#121212`/
+tinted navy); **any background gradient** (flat only; the one exception is hero
+heading text); flat hero heading colour (apply the approved text gradient); **the
+purple/blue "AI gradient" - the single most common AI fingerprint** (flat neutral
+base + one accent); oversaturated accents (keep under ~80%); more than one accent;
+mixing warm and cool grays; generic pure-black `box-shadow` (tint toward the
+background hue); zero-texture flatness (subtle noise/grain, never a gradient);
+inconsistent lighting direction (one light source); a random dark section in a light
+page or vice versa; empty sections with no depth (masked low-opacity imagery or a
+pattern; `https://picsum.photos/seed/{name}/1920/1080` as a placeholder, never an
+ambient gradient).
+
+### Layout
+Everything centred/symmetrical (break it); three equal card columns as the feature
+row (keep 3-5 benefits as content, but zig-zag/asymmetric/scroll/masonry as layout);
+`height: 100vh` (use `min-height: 100dvh`); complex flexbox percentage math (CSS
+Grid); no max-width container (~1200-1440px; hero capped ~680px); flexbox-forced
+equal card heights (allow variable/masonry); radius by feel (token scale +
+nested-radius formula); ad-hoc spacing (the spacing scale); no overlap/depth
+(negative margins to layer); symmetrical vertical padding (optical, usually more at
+the bottom); dashboard always a left sidebar (try top nav / command menu /
+collapsible); missing whitespace; CTAs not bottom-aligned in card groups; pricing/
+comparison list items starting at different Y (fixed-height title/price blocks);
+misaligned baselines across side-by-side elements; mathematically-but-not-optically
+aligned icons/text.
+
+### Interactivity and states
+Default easing (`ease`/`linear`/`ease-in-out` -> the base curve, 500ms movement /
+300ms colour-opacity, never under 200ms); content just "there" on scroll (rise+fade
+once, 600-800ms); scroll listeners (use `IntersectionObserver`/`whileInView`); nav
+welded to the top edge (float it, translucent blur); instant menu-icon swap (animate
+it); cramped mobile dropdown (full-height panel, links staggered ~60ms, under 400ms);
+no reduced-motion handling (swap movement for a fade); no hover state; no active/
+pressed feedback (`scale(0.98)`/`translateY(1px)`); missing focus ring; no loading
+states (skeletons, not spinners); no empty states (a composed getting-started view);
+no error states (inline, specific, never `alert()`); dead `#` links; no current-page
+nav indicator; scroll jumping (`scroll-behavior: smooth`); animating `top`/`left`/
+`width`/`height` (use `transform`/`opacity`).
+
+### Content
+Placeholder/stock people and repeated faces; suspiciously round numbers; generic
+brand names; filler words ("revolutionize", "supercharge", "cutting edge",
+"effortless", "transform your workflow", "world class"); vague value props
+("streamline"/"optimize" -> a measurable outcome); features with no outcome; weak
+CTAs ("Learn more"/"Submit" -> verb + what they get); competing CTAs above the fold;
+proof buried at the bottom; no risk reversal; loud/cute system messages (calm and
+specific); passive voice; placeholder/Latin text (a blocker); Title Case (use
+sentence case).
+
+### Component patterns
+Generic card (border + shadow + white bg -> background or spacing alone; cards only
+where elevation means hierarchy); single-side card border (all around or none);
+always one filled + one ghost button (add text/tertiary); pill "New"/"Beta" badges
+(square/flag/plain); accordion FAQ (keep 6-12 Q&A, change the pattern); three-card
+carousel testimonials with dots; three-tower pricing (emphasise the recommended tier
+by colour/weight, not height); modals for everything (inline/slide-over/expand);
+avatar circles only (squircles); sun/moon theme toggle (dropdown/system/settings);
+four-column footer link farm (main paths + legal only).
+
+### Iconography and imagery
+Lucide/Feather/Material icons (-> the approved set); cliche metaphors (rocket for
+"launch", shield for "security" -> bolt, fingerprint, spark, vault); inconsistent
+stroke widths; missing favicon; stock "diverse team" photos.
+
+### Code quality
+Div soup (semantic HTML); inline styles mixed with classes; hardcoded pixel widths
+(`%`/`rem`/`em`/`max-width`); missing/`alt="image"` alt text; arbitrary z-index like
+`9999` (a scale); commented-out dead code; **import hallucinations** (verify every
+import exists in the dependency file); missing meta tags (`<title>`, description,
+`og:image`, social).
+
+### Strategic omissions (what AI builds forgets)
+Legal links; back navigation; a custom 404; form validation; a skip-to-content link;
+cookie consent where required (see `maggie-legal`); landing-page indexing not
+considered (`noindex` ad-only/time-bound, real title/meta/internal-links/AEO FAQ for
+evergreen - hand SEO specifics to `maggie-seo-geo`).
+
+## Fix priority (max impact, min risk)
+
+1. Font swap - biggest instant win, lowest risk.
+2. Colour and surface cleanup - snap to the palette, remove background gradients.
+3. Hover / active / focus states - makes it feel alive.
+4. Layout and spacing - grid, max-width, spacing scale, nested-radius formula.
+5. Motion pass - base curve, IntersectionObserver reveals, floating nav, mobile menu.
+6. Replace generic components - swap cliche patterns for the alternatives above.
+7. Loading / empty / error states - makes it feel finished.
+8. Copy pass - cut cliches, add specificity, fix CTAs.
+9. Type-scale polish - the premium final touch.
+
+## Rules
+
+- Work with the existing stack; do not migrate frameworks or styling libraries.
+- Do not break functionality; test after every change (maggie-design's verify/QA).
+- Report the diagnosis before fixing; let the user veto items.
+- Check the dependency file before importing any library; check Tailwind v3 vs v4
+  before touching config; no framework -> vanilla CSS.
+- Small, targeted, reviewable changes over big rewrites.
+- Never invent a design value; if it is in neither this audit nor the visual
+  defaults nor the project's system, ask.
+
+## Credits
+
+Adapted (not transcribed) from
+[`elayadesign/redesign-skill`](https://github.com/elayadesign/redesign-skill)
+`redesign-existing-projects` by Elaya (MIT), which adapts audit structure and
+content-realism checks from [`Leonxlnx/taste-skill`](https://github.com/Leonxlnx/taste-skill)
+by Leon Lin (MIT).

package/references/video-timeline-model.md

@@ -0,0 +1,110 @@
+# Marketing-video timeline model
+
+An engine-neutral, provider-neutral data shape for "assemble these clips, images,
+text, captions and audio into a video", distilled from the open NLEs (MLT /
+Shotcut / Kdenlive, OpenShot, Olive). Used by `maggie-video`. We adopt the **data
+shape** (an uncopyrightable idea), never their code - MLT/Shotcut/Kdenlive/OpenShot/
+Olive are LGPL/GPL. It renders through the **ffmpeg binary** (the common
+denominator, arm's-length), or optionally through `melt` as a GPL external tool.
+
+## Conventions (chosen for LLM-friendliness)
+
+- **Seconds** (floats) at the authoring layer, not frames (OpenShot-style).
+- **`position`** = where a clip starts on the timeline; **`start`/`end`** = the trim
+  within its source (OpenShot's split; MLT calls the trim `in`/`out`).
+- **`z`** = track stacking; higher is on top (mirrors MLT `b_track` over `a_track`,
+  OpenShot's higher layer number).
+- **Keyframes** as `{t, v, ease}` arrays, ease in `linear | hold | smooth | bezier`
+  (MLT's linear/discrete/smooth + OpenShot's Linear/Constant/Bezier).
+- **Relative positions/sizes** (`"80%"`, 0..1) + named anchors, so it is
+  resolution-independent.
+
+## The model
+
+```jsonc
+{
+  "output": { "width": 1080, "height": 1920, "fps": 30, "format": "mp4",
+              "vcodec": "h264", "acodec": "aac", "duration": "auto" },
+  "assets": {
+    "shot1": { "type": "video", "src": "footage/a.mp4" },
+    "product": { "type": "image", "src": "footage/product.jpg" },
+    "logo": { "type": "image", "src": "brand/logo.png" },
+    "vo": { "type": "audio", "src": "audio/vo.mp3" },
+    "music": { "type": "audio", "src": "audio/track.mp3" }
+  },
+  "tracks": [
+    { "id": "main", "kind": "video", "z": 0, "clips": [
+      { "asset": "shot1", "start": 2.0, "end": 7.0, "position": 0.0, "fit": "cover",
+        "effects": [ { "type": "zoom", "keyframes": [
+          {"t":0.0,"v":1.0,"ease":"linear"}, {"t":5.0,"v":1.12,"ease":"smooth"} ] } ] },
+      { "asset": "product", "position": 5.0, "duration": 4.0, "fit": "cover" }
+    ] },
+    { "id": "overlay", "kind": "video", "z": 10, "clips": [
+      { "type": "text", "text": "50% OFF TODAY", "position": 1.0, "duration": 3.0,
+        "style": { "font": "Inter-Bold", "size": 96, "color": "#FFFFFF", "box": "#E11D48", "align": "center" },
+        "rect": { "x": "10%", "y": "70%", "w": "80%", "h": "15%" },
+        "effects": [ { "type": "opacity", "keyframes": [
+          {"t":0,"v":0}, {"t":0.4,"v":1}, {"t":2.6,"v":1}, {"t":3.0,"v":0} ] } ] },
+      { "asset": "logo", "position": 0.0, "duration": 9.0,
+        "rect": { "x": "80%", "y": "5%", "w": "15%", "h": "auto" } },
+      { "type": "captions", "src": "audio/vo.srt" }
+    ] }
+  ],
+  "transitions": [ { "type": "crossfade", "between": ["shot1","product"], "position": 5.0, "duration": 0.5 } ],
+  "audio": [
+    { "asset": "vo", "position": 0.5, "gain": 0 },
+    { "asset": "music", "position": 0.0, "gain": -18, "ducking": { "under": "vo", "amount": -12 },
+      "fade_out": { "at": 8.5, "duration": 0.5 } }
+  ]
+}
+```
+
+Minimal required: `output{width,height,fps,format}`, `assets{}`, one video track of
+`clips[]` each with `asset`+`position`+(`duration` or `start`/`end`). Everything
+else is additive.
+
+## Field crosswalk (stay compatible with any backend)
+
+| this model | MLT | OpenShot | Olive |
+|---|---|---|---|
+| asset `src` | producer `resource` | `files[].path` | footage node |
+| `start`/`end` (trim) | `in`/`out` (frames) | `start`/`end` (sec) | `kMediaInInput` |
+| `position` (timeline) | playlist order + `blank` | `position` (sec) | `ClipBlock.in()` |
+| track / `z` | playlist in multitrack | `layer` number | block in sequence |
+| overlay | `composite` transition | higher layer | graph edge |
+| keyframe ease | `linear`/`discrete`(`|`)/`smooth`(`~`) | Linear/Constant/Bezier | kLinear/kHold/kBezier |
+| time base | frames | seconds | rational |
+
+## Rendering through ffmpeg (default, no GPL linking)
+
+Compile the model to one `filter_complex`:
+
+- **trim / in-out:** `-ss start -t dur -i a.mp4`, or `trim=start=..:end=..,setpts=PTS-STARTPTS`.
+- **fit to canvas:** `"cover"` = `scale=W:H:force_original_aspect_ratio=increase,crop=W:H`;
+  `"contain"` = `...decrease,pad=...` (see [ffmpeg recipes](ffmpeg-recipes.md)).
+- **sequence:** `concat` back-to-back; `overlay=enable='between(t,P,P+D)'` for timed overlays.
+- **crossfade:** `xfade=transition=fade:duration=0.5:offset=5.0`; audio `acrossfade`.
+- **text / lower-thirds:** `drawtext=...:enable='between(t,1,4)'`; animate via `x=`/`alpha=` expressions in `t`.
+- **logo:** `overlay=W*0.8:H*0.05`. **captions:** `subtitles=vo.srt`.
+- **audio mix + ducking:** `amix`, `volume`, `sidechaincompress` (music under VO), `afade`.
+- **keyframes:** ffmpeg `t`-expressions (`alpha='if(lt(t,0.4),t/0.4,1)'`) or `zoompan`; for rich curves precompute per-frame values from the `{t,v,ease}` arrays.
+- **output:** `-c:v libx264 -r fps -pix_fmt yuv420p -c:a aac out.mp4`.
+
+`mifi/editly` (MIT) and `Zulko/moviepy` (MIT) are working prior art that this JSON
+shape renders through ffmpeg without any GPL engine.
+
+## Optional higher-fidelity backend: melt (GPL, external)
+
+The same model can emit **MLT XML** and render with
+`melt project.mlt -consumer avformat:out.mp4` - keyframes map to MLT's
+`frame=value` animation strings and `composite`/`luma` transitions. Treat `melt` as
+an optional external tool behind a provider-adapter boundary (see
+[provider adapter contract](provider-adapter-contract.md)); it is GPL, invoked at
+arm's length, never linked or vendored.
+
+## What belongs where
+
+- **This reference:** the data model, the crosswalk, the ffmpeg compilation map, the
+  keyframe/ease vocabulary, the licensing note - stable and engine-neutral.
+- **`maggie-video` skill:** channel presets, caption/CTA safe-areas, the operational
+  ffmpeg command layer (via `maggie_video.py`), and tool wiring.