Context​

The runtime today is deliberately lightweight and lazy:

• Lenis (the smooth-scroll library) is already vendored, but private to one module (Scroll Loop).
• GSAP + ScrollTrigger is private to one module (Scroll Motion) and loads only on pages that use it.
• The sticky scroll modules (Scrollytelling, Sticky Stack, Horizontal Scroll, Scroll Color Shift, Image Sequence) are library-free — each reads getBoundingClientRect() in its own small requestAnimationFrame loop.
• A shared scheduler already exists — window.upwAnimRaf — one rAF loop that many modules subscribe to and that pauses itself while the tab is hidden.
• The theme already ships a CSS "Smooth Scroll for Anchor Links" toggle (scroll-behavior: smooth), which is a different thing from inertia wheel-smoothing.

There is no shared GSAP loader, no shared scroll-progress helper, and no shared reduced-motion helper — each is either reimplemented per module or owned privately by one.

Options considered​

Where smooth-scroll lives:

• Extend the theme's existing "Scrolling" group. Keeps all scroll UX in one place — but it lives in the theme, off-pattern for an engine feature, and it conflates CSS anchor-smoothness with real inertia scrolling under one label.
• A new Animation Engine module (chosen). Mirrors the four existing site-wide effects (Cursor, Page Transitions, Preloader, Scroll Progress): its own Theme Settings sub-tab, ships assets only when enabled, and keeps motion where motion belongs. Labeled "Smooth (inertia) scrolling" so it reads as clearly distinct from the theme's anchor-link toggle.

How the scroll clock is unified:

• Port every sticky module to ScrollTrigger. Industry-standard and powerful — but it's a large, behaviour-parity-risky rewrite of the flagship Scrollytelling (pinned stage, backdrop scrub, persist ranges, published progress), and it would force GSAP to load on every page that uses any of these effects. That fights the engine's "ship only what a page uses" principle.
• Reuse the shared upwAnimRaf loop (chosen). Extract two shared helpers (upwScrollProgress and upwReduceMotion) and move each sticky module's per-frame reader onto the one ordered loop that already pauses off-screen. Same felt result — one smooth, synchronized scroll — with no wholesale rewrite and no forced GSAP.

Decision​

A new engine module (smooth-scroll) providing inertia smooth-scroll site-wide, and a shared-loop unification: sticky modules ride upwAnimRaf and read from shared progress/reduced-motion helpers, rather than being ported to ScrollTrigger.

Why​

• Risk. A faithful ScrollTrigger port of Scrollytelling is a project on its own; the shared-loop path moves the tick, not the logic, so behaviour can't drift.
• Page weight. The shared loop keeps GSAP where it already earns its place (Scroll Motion). Lenis still bridges to ScrollTrigger when it's present (gsap.ticker drives Lenis; lenis.on('scroll', ScrollTrigger.update)), so scroll-motion pages stay in lockstep — but a page with only a smooth background and a sticky stack never pays for GSAP.
• Reuse over rebuild. upwAnimRaf already gives ordered updates and tab-hidden pausing for free; we add the two helpers the engine was missing and adopt them everywhere, which also closes existing gaps (e.g. Scroll Color Shift had no JS reduced-motion guard).
• On-pattern. Smooth-scroll as a site-wide engine module is copy-paste consistent with Cursor / Page Transitions / Scroll Progress — same options shape, same enqueue gating, same config bridge — so it's predictable to build and to maintain.

Status: Accepted — Phase 0 of the motion roadmap. Increment 1 (the smooth-scroll module) is built first; the sticky modules move onto the shared loop one at a time after.

Context​

The field runs the snippet with three things already in scope — el (the element), tl (a gsap.timeline() already tied to a ScrollTrigger on el, start top 80%), and gsap. Two constraints follow from the runtime that a general GSAP tool would ignore:

• The timeline and its trigger are provided. You don't write gsap.timeline() or ScrollTrigger — you add tweens to tl. The trigger start is fixed in the runtime (runSnippets).
• Only GSAP core + ScrollTrigger are guaranteed. SplitText/MorphSVG and other plugins load only when their preset effect is used elsewhere on the page, so a snippet can't rely on them.

Options considered​

• A general GSAP playground. Expose timelines, ScrollTrigger config, all plugins — teach GSAP broadly. But most of it produces code that won't paste into the field (the field already owns the timeline/trigger, and the plugins may be absent), so it would mislead exactly the beginners it's meant to help.
• Mirror the field's contract (chosen). Generate only tl.from/to(el | el.querySelectorAll(...), {…}) chains — the shape the field runs — using core tweens, eases, stagger and the position parameter. Preview by executing the generated code the same way the plugin does (new Function('el','tl','gsap', code) on a fresh timeline), so what you see is what you paste.

Decision​

The generator emits snippets against the exact contract: el / a provided tl / gsap, core-only, trigger fixed. Everything it produces pastes and runs unchanged. Exposing the trigger start / scrub is explicitly deferred — it would require extending the runtime (runSnippets reading those off the element) in lockstep, so it's a "change both sides together" follow-up, not a v1 knob.

Why​

• Correctness over breadth. A generator whose output sometimes doesn't work is worse than none — it burns the trust of the beginner it targets. Matching the contract guarantees every snippet pastes.
• It teaches the right mental model. The visible code reinforces "you're handed a scroll-tied timeline; add tweens to it" — which is the one idea that unlocks the field.
• Single source of truth. The preview runs the generated string through the plugin's own execution shape, so the tool can't drift from the runtime — if it previews, it ships.
• Room to grow honestly. When we want trigger/scrub controls, we extend the runtime and the generator together, keeping the "what you see is what you paste" guarantee intact.

Status: Accepted. Lives at /animation-engine/gsap-generator.

Update (same day): the deferred trigger controls were added on both sides together — the exact "change the runtime and the generator in lockstep" follow-up this decision anticipated. The Custom Code field gained Trigger start + Scrub options (the runtime runSnippets reads them off the element); the generator mirrors them as a preview mode (play vs. a scrub slider) and a "set these in the builder" hint. The guarantee still holds: the generated snippet is only the tween chain — trigger/scrub are field options, not code — so what you paste always works.

Update 2 (same day): v1 mirrored the built-in presets, which made it redundant with the module — there's no reason to hand-write an effect that's already a tile. So it grew into a GSAP Timeline Studio that does what the options can't: multi-target choreography on one timeline, a full per-property palette (2D + real 3D transforms, filters, clip-path, colour), keyframe steps, loop/yoyo, and advanced stagger. The core decision is unchanged and is exactly what keeps this safe — still contract-faithful and core-only (the provided tl, GSAP core, no plugins), so every composed snippet still pastes and runs. "Fuller tool" ≠ "full GSAP playground": it went deeper WITHIN the contract, not outside it.

Context​

Every subsystem that needed to write to uploads had hand-rolled its own wp_upload_dir()['basedir'] . 'unysonplus-<x>' path. The result: nine-plus UnysonPlus folders littering the uploads root next to the user's own year/month media folders, with no obvious grouping and nothing to enforce a convention on the next feature that needed a folder (the Lottie and Rive work had just added two more).

The blocking worry with any move is stored URLs: if a folder's file URLs are persisted in the database (post meta / options), renaming the folder 404s them. So before deciding, we mapped every folder: which are computed (URL rebuilt from the dir helper each request — safe to move) versus stored (URL persisted — needs migration). The finding was decisive: almost everything is computed — regenerable caches (asset-optimizer, generated CSS) or re-downloadable content (icon-packs, templates, designs, presets) whose URLs are recomputed per request. The only DB-stored URLs are the Lottie/Rive src values, and those are brand-new/unreleased with essentially no real data. That turned a scary-looking move into a low-risk one.

Options considered​

• Leave the sibling folders as-is. Zero risk, zero work — but the uploads root stays messy and every future feature invents its own top-level folder, compounding the sprawl.
• Consolidate under one uploads/unysonplus/<subdir>/ parent, via a shared helper — chosen. Tidy root, one obvious home, and a single chokepoint (fw_upw_uploads_dir()) that makes the next folder automatic and impossible to get wrong.
• Consolidate but keep each subsystem building its own path (just change the strings). Rejected — it fixes today's mess without preventing tomorrow's; the value is the enforced convention, not the one-time rename.

Decision​

All plugin- and theme-written uploads move under wp-content/uploads/unysonplus/<subdir>/ (icon-packs, lottie, rive, templates, designs, shortcodes, asset-optimizer, css, presets). A single shared helper fw_upw_uploads_dir( $subdir ) builds every path; each dir helper (plugin and theme) routes through it, and new code MUST use it rather than hand-rolling a path. A one-time, flag-guarded migration (fw_upw_migrate_uploads(), on admin_init) renames the legacy siblings and the loose generated CSS into the new layout. The lone DB-stored URLs (Lottie/Rive src) are rewritten on read by fw_upw_normalize_legacy_upload_url(), so values saved before the move still resolve.

Why​

A single parent is simply how a well-behaved plugin should treat the shared uploads dir — easy to find, back up, or delete as a unit, and it stops the root from filling with our folders. But the real win is the shared helper as a chokepoint: the sprawl happened because there was no single place that owned "where do we put uploads," so every feature answered it independently. Centralising that answer means the convention enforces itself — the next folder is one fw_upw_uploads_dir('thing') call, already in the right place. The migration + read-time normaliser make the move invisible to existing sites, which is what made it safe to do now rather than deferring it forever.

Status​

Accepted.

Context​

Animated icons are an opt-in extension: activating it reveals an "Animated" tab in the icon picker and lets you choose which animation technologies are enabled. Those choices started on the extension's own settings page (settings-options.php → Extensions → Animated Icons → Settings).

Meanwhile, all other icon configuration already lives in Theme Settings → Icons — an Icon Settings box whose sub-tabs are Library / Browse / Upload (which webfont packs and SVG libraries are enabled, catalog installs, custom uploads). So a user configuring icons had to look in two places: packs in Theme Settings → Icons, animation technologies buried under Extensions.

Two codebase precedents pointed the way. The Animation Engine extension does not ship a settings page at all — it contributes a section to Theme Settings via the fw_settings_options filter while active. And the Icons page is already a tabbed box, so a fourth tab slots in cleanly.

Options considered​

• Keep the extension's own Settings page. Self-contained and extension-scoped (persists across theme switches). But it splits icon configuration across two screens and hides the toggles where few people look — the opposite of discoverable.
• Fold the toggles into Theme Settings → Icons as an "Animated" sub-tab — chosen. Co-locates every icon setting on one screen, puts the toggles exactly where someone configuring icons is already looking, and matches the Animation-Engine-style "extension contributes to Theme Settings" convention. The tab appears only while the extension is active.
• A separate top-level Theme Settings tab (e.g. "Animated Icons"). More discoverable than the extension page, but it divorces the toggles from the packs they belong with; a sub-tab of Icons is tighter.

Decision​

Move the toggles into Theme Settings → Icons as a fourth "Animated" sub-tab (beside Library / Browse / Upload) and drop the extension's standalone settings-options.php. The Icons page exposes a filter (unysonplus_icons_animated_settings) that it fills into the box; the extension hooks that filter only while active, so with the extension off the Icons page shows just Library / Browse / Upload. The four gate filters (fw_icon_lottie_enabled / _rive / _svg_animation / _raster) now read their values from theme settings (fw_get_db_settings_option) instead of extension settings. No data migration was needed — the feature is unreleased.

Why​

It removes the "two places to configure icons" split: packs and animation technologies now sit on one screen, in the order you'd reason about them. It follows the framework's own pattern (an animation extension augmenting Theme Settings rather than shipping a bespoke page), so it reads as native rather than bolted-on. And the injection-via-filter keeps the coupling clean — the Icons page owns the tab slot, the extension owns the contents, and nothing appears when the extension is inactive.

The one deliberate trade-off: settings are now theme-scoped (a theme switch resets them) rather than extension-scoped. That is a feature, not a regression here — the pack toggles the animated toggles now sit beside are also theme-scoped, so the whole Icons screen behaves as one consistent unit.

Status​

Accepted.

Context​

Each column is a separate addable-popup option, and each uses jQuery-UI sortable() with axis:'y' — one vertical list per column, so drags are column-locked. The data already lives as an array of per-item JSON blobs inside each column's option value.

Two facts made the answer easy:

• jQuery-UI sortable has connectWith built in — dragging between lists is a native feature of the library already in use. No new drag engine.
• A new post type would be pure over-engineering. The item data is already self-contained JSON in the option value; a post type would add a whole storage/query layer for zero benefit.

Options considered​

Decision​

Add an opt-in connect_group to the addable-popup option type. Two or more addable-popups that share the same non-empty group id interlink (connectWith); empty (default) stays self-contained. The id is scoped per logical group — one footer row's columns, one header bar's Left/Center/Right — so unrelated addable-popups on the same settings page never interlink. Empty connected columns stay visible as drop targets. The header/footer column helpers opt in by passing the bar/row id.

Why — and the trap the prototype caught​

The reassuring part (self-contained item data) hid a real trap that only a test on a real install exposed. My first read was "the value is collected by DOM position, so a moved item just works." Wrong: the settings form saves via native $el.serialize(), and each item's input name encodes its column (fw_options[…][col_1][]). A dragged item kept its origin column's name, so it moved visually but reverted on save. The fix is to re-key the moved item's input name on jQuery-UI receive to the receiving column (the name template captured from that column's default item, so it works even for an empty column).

The lesson: "it drags and drops" in the DOM is not the same as "it saves." When a framework serializes by input name, moving a node between lists isn't enough — the name has to move too. Prototyping against the actual save path, rather than reasoning about it, is what turned a plausible-but-wrong assumption into a shipped, verified feature (drag → save → reload round-trip confirmed in the database).

Status: Accepted. Live on all footer rows and header bars; the connect_group flag is reusable by any addable-popup that wants cross-list DnD.

Context​

We first did this by hand on a demo (negative margin + a dark gradient on the theme footer). It looked right, but it hard-coded a footer height, a scrim colour, and assumed the last section was a tall pinned scene. As a reusable option it needs to work on any site without those assumptions.

The footer already has a Footer Layout settings tab (background, colours, border, spacing). The front end renders #colophon.footer and reads settings via fw_get_db_settings_option(). So the natural home is a new toggle there that adds a class the CSS/JS act on.

Options considered​

• Leave it per-site (hand-CSS each cinematic site). No new surface, but every such site re-derives the same fragile margin/scrim math.
• A full "footer mode" system (band / overlay / sticky / …). Over-built for one real need today.
• A single switch toggle — "Overlay on last section" (chosen). One option, one class, minimal runtime.

Decision​

Add Footer → Layout → "Overlay on last section" (footer_overlay_last_section, a yes/no switch, default no). When on, footer.php adds footer--overlay to #colophon. A tiny inline runtime measures the footer height into --footer-overlay-h and adds footer--overlay-on — which pulls the footer up by that height and raises its z-index — only when the page's last section is ≥ 70vh tall. Three deliberate constraints:

1. Positioning only. The toggle moves the footer; it does not restyle it. The footer's own footer_background and text/link colours stay in the user's hands, so the option composes with the existing Footer settings instead of fighting them.
2. JS-gated to a tall last section. Overlaying a short last section would look cramped, so the runtime engages only when the last section is tall enough to sit on; otherwise the footer stays a normal band. Graceful, content-aware fallback with no author configuration.
3. Transparent background by default in overlay mode. footer--overlay-on resolves its background to var(--footer-bg-color, transparent) — so with no explicit footer background the final scene shows through (the intended look), while a user-set scrim still wins.

Why​

• It's a real, recurring pattern (any cinematic / scroll-story page ends better on its last scene than on a blank band), so it earns a first-class option rather than living as per-site CSS.
• Positioning-only keeps it predictable. The #1 way a "layout" toggle goes wrong is silently overriding the user's colours/background; scoping the option to where the footer sits avoids that entirely and lets it stack with everything already in Footer settings.
• The height + tallness are runtime facts, not author inputs. Measuring the footer and checking the last section's height means the author flips one switch and it does the right thing (or safely nothing) regardless of their footer's size or their last section — no magic numbers to tune.
• Demo stays independent. The cinematic demo that inspired this keeps its own custom footer and overlay CSS; the new option serves sites built on the standard footer builder. Two surfaces, no coupling.

The general lesson: when promoting a demo hack to a framework option, strip it to the one thing it must own (here, position), and let content-measured runtime facts replace the hard-coded constants the hack relied on — so the option is one switch that can't fight the user's other settings.

Context​

The Animated kind (part of the unified icon engine — see the icon-v3 promotion) plays animations with the bundled lottie-web SVG-light build: window.lottie.loadAnimation({ path: src }), which fetches a URL and JSON.parses it. The upload endpoint validates the body is a real Bodymovin export ("v" + "layers" keys). So today the pipeline is JSON end-to-end — a .lottie would be rejected on upload and would fail to render from a URL, because a .lottie is not JSON: it is a ZIP archive (a manifest.json + one or more animation JSONs + optional bundled image assets) that happens to carry a .lottie extension. Plain lottie-web can't open it.

The tempting assumption is that .lottie is "better for performance," especially with many icons on a page. It isn't — not in the way that matters. A .lottie is a zipped .json. Same animation inside; once the browser unzips and parses it, a .json and a .lottie become the identical in-memory animation and render with the identical cost. The format only ever affects delivery (bytes on the wire, number of requests), never render (CPU/GPU while the frames play).

That split is the whole decision:

• Download cost — format-sensitive. A .lottie is smaller on disk (~5–10 KB vs a ~20–40 KB raw .json). But web servers gzip/brotli text on the wire, and Lottie JSON compresses beautifully, so a single small .json already arrives at ~5–8 KB — the real-world gap shrinks to almost nothing.
• Render cost — format-insensitive. Twenty animations playing at once cost 20× the CPU whether they were delivered as .json or .lottie. The thing that actually janks a page with many animated icons is the SVG renderer doing 20× the work per frame, and no file format changes that.

The one genuine .lottie advantage — bundling many animations (with shared/deduped assets) into one file, i.e. one request instead of twenty — does not apply here: the icon picker stores one animation per field, so there is nothing to bundle.

Options considered​

• Keep JSON-only — chosen. Matches the lean lottie-web runtime already bundled, keeps the whole store/preview/render pipeline unchanged, and loses nothing that matters for one-icon-per-field usage.
• Swap in the dotLottie player (@lottiefiles/dotlottie-web, WASM) so .lottie loads natively — rejected for now. It adds a ~200 KB+ WASM runtime and a different API across three files (picker preview, syncLottie, the frontend hydrator), for a format whose only edge is download size. That fights the plugin's lean-DOM ethos.
• Accept .lottie uploads and unzip → extract the inner JSON (PHP ZipArchive, keep lottie-web) — deferred as a convenience, not a perf feature. It lets users drop in a file they downloaded from LottieFiles without converting it first. Caveat: a .lottie that bundles raster images would need those extracted and path-rewritten (or inlined) or they render blank — rare for vector icon animations, but worth a graceful warning.

Decision​

The Animated icon value type stays Lottie JSON only. .lottie is not adopted for performance, because it offers none over gzipped JSON at one-animation-per-field scale. If we add .lottie later it will be purely a convenience (unzip → extract JSON on upload, keeping the existing lottie-web player), not a rendering or bundling win.

Why​

The benefit people expect from .lottie — "lighter pages with many animations" — is a misattribution: format governs download, not render, and the download gap is already erased by server compression. The real cost of many animated icons is render work, which is identical across formats and is better addressed by behavior (pause off-screen animations, keep them simple, or fall back to a static image until hover) than by packaging. So there is no performance reason to take on a heavier player or an unzip step now. The door stays open to accept .lottie uploads for user convenience — but framed honestly as convenience.

Status​

Accepted. Revisit only if the icon engine ever ships bundles of many animations per element (the one case where dotLottie's single-file packaging would genuinely cut requests), or if users repeatedly hit the "I downloaded a .lottie and it won't upload" wall — at which point the unzip-to-JSON convenience path is the minimal answer.

Context​

We already had a single Photo Scatter gallery with a scroll_cycle mode that cycles image batches automatically (batches = images ÷ cards-per-set). That's great when you just want images cycling. But the reference site pairs text with each batch — a centered heading that's synced to that batch's scatter. A single gallery has one set of options and no per-batch text, so it can't express "batch 2 has these images, this heading, and enters from the top." The user's instinct was to reach for one gallery shortcode per batch.

Options considered​

• One cycling gallery (scroll_cycle). Simplest, one element — but it has a single from/exit and no place to attach per-batch text. Can't do "different heading + different images per batch."
• Five separate Photo Scatter shortcodes, one per batch. Each naturally has its own images and enter/exit. But free-floating galleries all read the same scroll position, so they'd animate simultaneously, not in sequence; making them play in order means hand-gating each to a scroll range, and you manage five modals that can drift.
• Each batch = a scene in one scrollytelling Stage (chosen). One pinned Stage; every beat scene is a column holding a centered heading and its own Photo Scatter of that batch's images. The Stage already sequences scenes in scroll order, so batch 2 waits its turn automatically, and text ↔ image sync is free because they share one scene on one timeline.

Decision​

Build per-batch sections as scenes in a single Stage. Each batch is one editable column: a centered heading + a photo_scatter (its own images, center_clear:'yes' so the photos ring the title, a single set so all its images scatter together, its own from/exit). Different images, text, and direction per batch — each batch fully replaceable in the builder.

The one framework change that made it work: a photo_scatter nested in a Stage now reads its own scene's scroll slice. The Stage publishes each beat scene's index (__beatIndex); the gallery remaps the story's global progress to [beatIndex, beatIndex] (the same mechanism a ranged persist layer already used for [from,to]). So the scatter flies in, holds, and sweeps out exactly as its scene enters and leaves. A new "Keep center clear" option rings the cards around the middle so the heading stays readable.

Why​

• The Stage is the sequencer. The reason five separate galleries fail — no coordination — is exactly what a scrollytelling Stage provides for free. Scenes play one at a time, in order.
• Sync comes from sharing a scene. Text and images on the same scene share one scroll timeline, so they enter and leave together with no manual alignment. Scene-local remapping is what ties the scatter's motion to that.
• Editability is preserved and even improved. Each batch stays one column (a title + a gallery) — the "every element user-replaceable" rule holds. And per-batch images are cleaner here than in the single cycling gallery, where all images share one pool with no way to say "these belong to batch 2."
• The single scroll_cycle gallery still has its place — when you want images cycling with no per-batch text, it's the lighter choice. Two tools, two jobs: cycle-in-one-gallery for pure image batches, scene-per-batch when each batch carries its own copy.

The general lesson: when repeated content needs to play in sequence and stay in sync with text, reach for the scrollytelling Stage's scene model and let child elements read their scene's slice — not a pile of independent elements racing the same scrollbar.

Context​

Inspecting the source markup, the underline is not an SVG at all. It is two animated PNGs (APNG) layered in a wrapper:

<div class="relative">
  <img class="in-img … invisible" data-id="in-hero underline"   src="…/hero underline in.png">
  <img class="idle-img …"         data-id="idle-hero underline" src="…/hero underline default.png">
</div>

So the source authors each hand-drawn accent as a short draw-on clip (…in.png) and a looping idle clip (…default.png), both exported as APNG, and a little JS toggles between the two <img>s: the intro plays once when the section enters, then the idle loop takes over. Both files carry an acTL chunk (confirmed) — they are genuinely animated PNGs, ~600×45.

Why APNG and not SVG here: these are irregular, textured, multi-stroke doodles (a double scribble with pencil grain). Reproducing that as an SVG stroke-draw would mean hand-tracing paths and would still miss the texture. A designer can draw and export the two clips directly; the web just plays them. It's the right tool for hand-drawn assets.

The reproduction algorithm (and the one non-obvious part)​

We matched the technique in the demo, but adapted to a CSS-background underline instead of two <img>s:

1. Idle = the CSS background. …-idle.png (the looping APNG) is set as the <em> underline's background-image, so every emphasized word subtly waves with no JS at all.
2. Intro = a JS swap on enter. A tiny registry-driven runtime ([selector, name, ms] rows) watches each registered element with an IntersectionObserver; on first enter it sets the background to …-in.png, then after the intro length clears the inline style so it hands back to the CSS idle loop.
3. The crux — restart via a cache-bust query string. An APNG plays once when it is first decoded and then holds its last frame; there is no DOM API to rewind it. To make the intro play on enter (not merely on page load), we append ?t=<Date.now()> to the …-in.png URL, which the browser treats as a new resource and decodes fresh — restarting the animation from frame 0. Without that query string the draw-on would only ever fire once, on load, off-screen.

Options considered​

• Animated SVG (stroke-dashoffset draw-on) — clean and tiny, but can't reproduce a textured multi-stroke doodle without hand-tracing, and still looks like a vector line, not a pencil.
• A single static PNG (what the demo had) — no animation at all; the accent read as flat.
• Two-state APNG (in → idle), the source's own approach — chosen. Matches the reference exactly, keeps the hand-drawn texture, and stays authorable by a designer (draw two clips, export APNG).

Decision​

Use two APNGs per hand-drawn accent — an idle loop set as the CSS background, and an intro draw-on played once on enter via a cache-busted URL swap — then hand back to the idle loop. Keep the intro list in a small registry so more drawings are one line each.

Why​

It reproduces the effect faithfully (texture and all), it is authorable from design tools rather than hand-coded paths, and the whole runtime is a dozen lines. The single insight that makes it work is that an APNG restarts only when re-fetched, so the enter-triggered draw-on hinges on the cache-bust query string — the rest is just an IntersectionObserver and a timeout. If this graduates from the demo into a framework feature (an "animated drawing" element), this is the mechanism to generalize.

Context​

animated_heading is a purpose-built rotating headline: before-text + rotating words + after-text, with 6 rotation styles, a word-highlight, speed and colors — ~86 lines of self-contained JS, no dependency. The Animation Engine's Text Effects cover the same two concepts (typewriter, rotating words) plus 38 more, applied to any element's own text via a text_effect option. On paper that's duplication.

Options considered​

• Deprecate the shortcode — steer users to special_heading + text_effect: rotating_words. One implementation, but it requires the Animation Engine to be active — and the engine ships inactive by default (opt-in in Extensions). Out-of-box rotating headlines would break.
• Make the shortcode delegate to the engine when active — a hybrid renderer. Adds a hard dependency branch and loses the no-engine fallback that is the shortcode's whole value; the engine effect also expects the element's own text, not a before/words/after split.
• Keep it standalone, clarify positioning, and enrich it (chosen) — accept the small, intentional overlap; make the two easy to tell apart in the UI/docs; and deepen the shortcode so it's clearly the better tool for its one job.

Decision​

Keep animated_heading as a zero-dependency rotating headline, distinct from the engine. Its Animation picker now cross-references the Text Effects (and warns against stacking both), and the shortcode gained playback controls (loop once / pause on hover / randomize), typewriter caret controls, two rotation styles (blur, 3D-rotate) and two highlight styles (gradient, pill).

Why​

The deciding fact is that the Animation Engine is opt-in and off by default — a deliberate choice so the base plugin stays lean. That makes the shortcode the only rotating headline that works without asking the user to activate an extension, which is exactly the moment a beginner reaches for one. Beyond that, the two serve different mental models — "drop a rotating-headline element" vs. "sprinkle an effect onto any text" — and the shortcode's headline-specific options (before/after static text, per-word highlight, purpose-built rotation styles) are richer for that narrow job than the generic rotating_words effect. Folding it into the engine would trade a tiny amount of duplicated code for a worse out-of-box experience and a new dependency. The overlap is acceptable; the fix was positioning and depth, not consolidation.

Context​

Stepping through a mid-scroll stretch of the recording frame-by-frame, the "camera move" is an illusion: the backdrop itself translates sideways and scales up a touch as the scroll advances. There is no perspective shift, no parallax between foreground and background layers — the whole still image just pans and dollies. The insight came straight from watching it ("the camera panning is just an illusion of the background moving"), which is exactly right and is the entire trick.

That reframes the problem. We don't need footage or a WebGL camera; we need to transform a static backdrop by scroll progress. The scrollytelling Stage already publishes its 0→1 progress every frame (the --story-progress CSS var and el.__storyProgress), so the demo's first cut was a few lines of hand-CSS on the demo child theme: transform: scale(calc(1.16 + var(--story-progress) * 0.1)) translateX(calc((var(--story-progress) - 0.5) * -14%)) on the backdrop <img>. It worked — and that was the tell that this is a reusable capability, not a one-demo hack.

Options considered​

• Leave it as per-site hand-CSS. Cheapest, but every site that wants the effect re-derives the same transform math, has to know the --story-progress var exists, and risks stacking its transform against anything else on the image (a blur, a fit tweak). It also isn't discoverable in the builder.
• Bake it as footage / a frame sequence backdrop. Highest fidelity, but violates the standing rule that demo content stays live and user-replaceable, and it's heavy. A still image + a transform gets 95% of the look for kilobytes.
• Promote it to a Stage option (chosen). Add backdrop_motion (none / pan / dolly / pan_dolly) with motion_direction and motion_intensity, computed in the Stage's frame loop and applied to the backdrop container. Discoverable, reusable, and composes with the image's own CSS.

Decision​

Ship Backdrop Motion as a first-class scrollytelling Stage option. The module reads the three data-attributes at render time and, in the same rAF loop that scrubs the backdrop, sets a scale(...) translate(...) on the backdrop container element (not the <img>). The demo now uses backdrop_motion: 'pan_dolly' and drops its hand-CSS transform, keeping only the blur on the image.

Why​

• The illusion is the mechanism. Once you see the camera move is a moving backdrop, the honest implementation is a scroll-scrubbed transform — so the framework should own that math, not each site.
• Container, not image, is the right layer. Sites routinely style the backdrop image (blur for depth-of-field, object-fit). Transforming the container leaves the image's own CSS untouched, so the motion composes instead of fighting it. (The demo's first cut transformed the <img> and would have stacked against its blur rule — the migration to the option removed that footgun, and the kit doc now explicitly warns against writing a second transform on the image.)
• It keeps the "live elements, not footage" promise. A single still backdrop + a scrubbed transform reproduces the reference site's rendered camera glide while the backdrop stays a swappable Media layer — consistent with why we chose editable elements over baked cinematic footage in the first place.
• Intensity + direction make it a general tool, not a one-site constant: a gentle ~40 reads as a slow drift; higher values give a strong sweep, and the pan axis is author-chosen.

The broader pattern worth remembering: when a site's "expensive" motion turns out to be a simple transform driven by scroll, the win is to expose the published progress (which the Stage already does) and add a small, well-named option that scrubs against it — rather than either hand-coding it per site or reaching for footage.

Context​

The reference site achieves its look by pre-rendering the entire journey as 3D footage: the scattered file cards, the film strip, the device mockup, the camera pan — all of it is baked into the video, and the only live DOM on the page is the headings and the search box. That is why it looks flawless and also why, as a product to hand a user, it would be a dead end: you cannot replace a card, swap the device's screenshot, or change a photo, because none of those are elements — they are pixels in a movie.

That collides head-on with the reason UnysonPlus exists. The pitch is: capture a site you like for inspiration, then add or replace any element right in the page builder. A user converts a reference site as a starting point and then makes it theirs, element by element, entirely through the builder UI — the same principle already written into the "every media/content element must be user-replaceable" rule and the converter's whole purpose.

A practical fact sealed it: we only had pre-rendered sequences for the hero and the outro. There was no baked footage for the long middle journey, so its content was always going to be live elements regardless.

Options considered​

• Bake the journey as one scrubbed backdrop video/sequence (max fidelity). The camera pan, the scatter, the card rotations all come for free because they are in the footage. But the content is frozen: no swapping cards, screenshots, or copy in the builder. It turns the "starter you make your own" into a "video you cannot touch." Rejected — it breaks the core value even though it looks best.
• All content as live page-builder elements (galleries, image boxes, device mockups, text) animated with the Animation Engine over an optional decorative backdrop. Slightly less pixel-perfect than pre-rendered 3D, and it means building real scene-galleries (a scroll-driven scatter→organize morph, a device view-mode cycler, directional scene transitions) instead of getting them free from footage — but every element stays editable and replaceable. Chosen.

Decision​

Content is always live and user-replaceable; only the decorative backdrop may be baked, and even it stays an uploadable option. We replicate the motion (the pinned scene, the beats that cross-fade and pan, the scatter→organize, the device screen cycling) using live builder elements plus the scrollytelling Stage, not by freezing the content into a rendered movie. The new capabilities this requires — scene-based ("pinned Stage + beats") structure, new scene-galleries, and directional/whoosh transitions — get built as real, editable framework features rather than shortcuts baked into media.

Why​

Fidelity is worth nothing if the user can't edit the result. The one durable advantage UnysonPlus has over "just export the design as a video" is that everything on the page is a real element the user owns and can change. Chasing pixel-perfect parity by baking the camera ride would spend that advantage to win a screenshot contest. Building the motion out of live elements costs more engineering up front, but it is reusable across every future site (not just this one demo), it keeps the convert→customize promise intact, and it is what turns "capture for inspiration" into "capture, then make it yours." When fidelity and editability conflict, editability wins.

Context​

Two forces pulled against each other. The framework's whole promise is "native options before code" — a non-developer should build motion by clicking, not by learning an API. But GSAP is a real library that's already loaded, and refusing to expose any of it wastes a capability the site is already paying for. A blunt "add a GSAP code field" answers the power user and betrays the beginner; "never expose anything" does the reverse.

There was also a stated goal beyond either audience: the owner wanted the engine to help people learn GSAP and web animation "in our own way" — the builder as a teaching tool, not just a generator.

Options considered​

• Stay curated — keep the presets, add nothing. Simple, but the wall stays and nothing is learned.
• One raw GSAP code field — maximal power, minimal work. But it's the antithesis of the clean-DOM / no-code promise, a support and security burden, and it teaches nothing (you either already know GSAP or you don't).
• A graduated ladder (chosen) — expose GSAP in rungs, each optional, each a no-op at its default, with a rung whose entire job is to show the code the earlier rungs generate.

Decision​

Five rungs, shipped across engine 1.2.38–1.2.41, on the Scroll Motion module:

1. Presets — pick a tile, it looks good. Most users never leave here.
2. Advanced options (1.2.38) — the GSAP knobs the presets normally decide: easing (curated eases
   • a validated custom string), scrub smoothing, ScrollTrigger markers. Collapsed behind a single "Default" row; every field renders byte-identically to before when left alone.
3. Motion Sequence (1.2.40) — choreography without code: a Section plays its children's Reveal/Stagger as one gsap.timeline(), the steps are the children, one Overlap knob tunes the flow. (Its own decision entry covers the timeline→options translation.)
4. Show generated GSAP (1.2.39) — a read-only panel inside each effect that prints the exact gsap.from(el,{…}) the current settings produce, live. The teaching rung.
5. Motion Snippet (1.2.41) — a "Custom Code" effect: write your own GSAP with el / tl / gsap provided; the runtime manages lifecycle. The lossless escape hatch. (Security in its own entry.)

Why​

• Every rung is opt-in and default-inert, so the beginner experience is untouched — the ladder adds ceiling without raising the floor. That's what lets one panel serve both audiences.
• Rung 4 is the keystone. Exposing knobs (rung 2) or a code field (rung 5) is common; a panel that shows you the code your own clicks generate is not, and it's what turns the engine from a black box into a way to learn GSAP. The intended path is legible: build with options → read the generated GSAP → Copy → paste into a Motion Snippet → tweak. Each rung hands off to the next.
• It respects "native options before code" without pretending code never matters. Rungs 1–4 are all options; code only appears at rung 5, as the explicit, gated last resort — the same shape as styling's "everything is an option until Custom CSS."
• Reuse over new surface. Rungs 2 and 5 live inside the existing gsap_motion control; rung 4 is a value-less option type mirroring the 3D-gallery preview; rung 3 reuses the runtime's own config builder. No parallel systems.

Note on the capture pipeline​

The ladder also gave the site converter somewhere to put motion it detects but can't map to an option: an advanced-tuned effect, or — when nothing fits — a Motion Snippet reconstructed from the traced ScrollTrigger/transform data. Motion now has the same map → tune → snippet-fallback → report ladder that styling has (map → tune → Custom CSS → report).

Context​

WordPress already has a bar for "this user may supply raw markup/JS": the unfiltered_html capability (admins, and editors on single-site; nobody below). The naive design is "only show the code field to users who have it." But two things went wrong with that, discovered by building it:

1. Gating the choice corrupted saved data. The snippet lived as a custom choice in the Scroll Effect multi-picker. When the choice was only registered for capable users, any server-side re-validation that ran without that user context — notably json_to_shortcodes, which regenerates post_content — didn't see custom as a valid choice and silently reset the value to none. The snippet vanished on the next content regeneration.
2. Hiding UI is not a trust boundary. A hidden field is still POST-able; a custom role could expose it; and the value has to survive round-trips regardless of who's looking. "They can't see it" was never actually the security property.

Options considered​

• UI gate — only capable users see the field. Fragile (above) and not a real boundary.
• Save-time sanitize — strip the code on save for users without the cap (kses-style). Correct as defense in depth, but on its own it's brittle: it depends on the exact save path running kses, and the field's value shape isn't plain markup.
• Execution gate (chosen) — always allow the field and store the code; only ever run it when the current page's author has unfiltered_html, checked per request at output.

Decision​

The custom choice is always registered (so the value is never reset by re-validation). The code is base64-stamped into post_content as a data-upw-snip attribute — static, exactly like every other data-upw-g* attribute, so it survives without re-running shortcodes. Execution is gated at render: a footer script emits window.upwSnippetsOK = 1 only when the queried singular's author can unfiltered_html, and the runtime runs a snippet only if that flag is set. This mirrors the theme's existing page_custom_js, which checks the author capability at wp_footer output.

kses stripping the attribute from a non-capable user's save remains true as a second layer, but the primary guarantee is the per-request execution gate.

Why​

• The capability question is really "does the responsible author get to run JS on this page?" — and that's an author-and-request property, not a "who is currently editing" property. Checking the author at output is the only place that answer is stable and correct. It's also precisely how WordPress already treats page-level scripts, so it's a known-good model, not a bespoke one.
• Separating storage from execution fixes the fragility. The value is plain data that always round-trips; safety doesn't ride on the value being present or absent. A contributor-authored page can contain a snippet (e.g. pasted by an admin earlier) and it simply won't run until a trusted author owns the page — no data loss, no silent reset.
• Defense in depth without depending on any single layer. Execution gate (primary) + kses on untrusted saves (secondary) + reduced-motion skip + a new Function boundary that can't reach the options-render AJAX. Any one failing doesn't open the door.

Status​

Accepted. The rule generalizes: for any author-supplied executable content, store it as inert data and gate execution on the responsible author's capability per request — never rely on hiding the input. Applies to future snippet-like surfaces (custom cursors, custom shaders, etc.).

Context​

The Template Library ships as two repos: UnysonPlus-Template-Library-Extension (the plugin code) and UnysonPlus-Templates (the content it downloads — a catalog.json plus template JSON, fetched over raw.githubusercontent.com). Icon packs already have their own content repo (UnysonPlus-Icon-Packs), and a presets library was on the table. On that trajectory the org accretes a data repo per library type, which is organizational clutter for a solo maintainer.

Two facts made the call clear:

1. Code and content are not the same kind of repo. Each extension's manifest.php carries a github_update header the plugin's auto-updater keys off. That coupling is what forces one code repo per extension. Content repos have no such coupling — the client resolves a catalog via a filterable *_catalog_url() and fetches individual files by raw URL. Nothing about the updater touches them.
2. End-user cost is per-file, not per-clone. A site only ever wp_remote_gets the specific catalog.json and item files it needs; it never clones the repo. So consolidating content doesn't grow any site's footprint — repo size only affects the maintainer's own clone.

Options considered​

• A repo per library type (status quo trajectory) — clean isolation, but N repos to create, README, and remember; the clutter that prompted the question.
• One repo for everything, code included — rejected: merging extension code breaks the per-extension github_update auto-updater. Non-negotiable.
• One repo for all content, code stays split (chosen) — a single UnysonPlus-Library data repo with one self-contained subfolder per type (templates/, page-presets/, header-presets/, style-packs/, icon-packs/, …), each with its own catalog.json whose base_url points at that subfolder; each extension points its catalog URL at its subfolder.

On the presets library specifically, a second question surfaced: is it a browse-and-install of individual presets, or of packs? Component presets split into two natures — layout presets (Page, Header, Footer) are self-contained whole-region configs with no cross-refs, while style-token presets (Color, Typography, Button, Box) reference each other (a button preset points at a color slug). Installing a lone button preset can therefore dangle a missing reference; installing a lone header preset cannot.

Decision​

• One UnysonPlus-Library data repo, per-type subfolders, each self-contained. Extension code stays one-repo-per-extension (the updater requires it). UnysonPlus-Templates was renamed to UnysonPlus-Library; templates moved under templates/ with the catalog inside it, and the extension repointed. The install-path builder dropped its hardcoded templates/ segment so every library resolves items as base_url + <slug>/… within its own subfolder.
• Presets get the library by augmentation, not rewrite. The existing preset UI (a card grid with Apply / Upload JSON / Export current) stays; a Browse Library button is added next to Upload JSON. The library is simply the curated, browsable form of the upload path — an installed preset becomes another applyable card.
• Layout presets ship as singles; style tokens ship as cohesive packs. Page/Header/Footer presets are self-contained, so individual catalog entries are safe and highest-value. Color/Typography/Button/Box travel together as a coordinated style pack so nothing dangles.

Why​

• The split falls on the real seam. The only thing that must be one-repo-per-thing is what the auto-updater is wired to — the code. Everything the updater doesn't touch (content) is free to consolidate, and consolidating it removes clutter with no downside a site ever feels.
• Augmenting reuses a working flow. Presets already round-trip as exported/uploaded JSON, so a library is 90% built — Browse is just Upload with a catalog in front of it. Replacing the preset UI would throw away the Apply/Export plumbing for no gain.
• Match the distribution unit to the dependency graph. Self-contained things distribute cleanly as singles; interdependent things must travel as a set or they arrive broken. Shipping style tokens as packs is the same "install a consistent whole" principle that makes a page template safe to drop in.

Status​

Accepted. Rule of thumb going forward: split repos on the updater seam (code per extension), and consolidate everything the updater doesn't touch (all library content in UnysonPlus-Library). When adding a browsable library to an existing feature, prefer augmenting its current Apply/Upload/Export surface over replacing it, and let each item's dependency graph decide whether it ships as a single or a pack.

Context​

Users faked choreography by hand-tuning per-element delay values ("heading at 0, subtitle at 0.2, button at 0.4") — brittle, because changing one duration means re-tuning every downstream delay. That brittleness is exactly what timelines exist to remove: positions are relative, so the sequence holds together when any single tween changes. But a timeline is a code construct; the builder needed a shape a visual editor could express.

The framework had already solved a structurally identical problem twice: Sticky Card Stack and Scroll Story both treat "the child columns" as the ordered units of a Section-level effect.

Options considered​

• A keyframe/timeline editor UI — most faithful to GSAP, but heavy, and it drags the builder toward being an animation tool rather than a page tool.
• Per-element "start at N seconds" fields — familiar, but it recreates the brittle absolute-delay problem the timeline was meant to solve.
• A Section behavior where steps = children (chosen) — mark a Section as a Motion Sequence and its children's existing Reveal/Stagger animations assemble into one gsap.timeline() in document order; one Overlap knob sets how far each step starts before the previous ends.

Decision​

Motion Sequence (engine 1.2.40), a Section-level module mirroring Sticky Stack / Scroll Story. Turn it on and the descendant Reveal/Stagger steps play as one timeline on a single trigger (on-view or scrub). The steps are the children in builder order; Overlap is the only timing control. Children keep the effects they already have — the sequence only decides when each fires.

Why​

• The translation is "positions become one knob, steps become the children." .to(b) sequential, .to(c,'<') together, .to(d,'+=0.5') offset — the full position vocabulary collapses, for the common case, into "each step starts overlap seconds before the previous ends." A non-coder reads that as a single slider, not a timeline API.
• No new vocabulary. A child in a sequence uses the same Reveal it would use standalone; the runtime reuses its own compound() config builder, so a step is byte-identical either way (direction, distance, style, ease — including the Advanced ease). Existing pages gain choreography by flipping one Section option.
• It matches a shape the framework and its users already know (cards = columns, scenes = columns → steps = children), which is why it needed no new mental model and no new front-end asset — it rides the Scroll Motion runtime that's already present because the children use it.
• Scoped to Reveal/Stagger first. Those are the 95% choreography case (heading → subtitle → button) and the two effects that share the entrance config builder; other effects stay standalone. Per-element after/with/offset positioning is the natural next increment, once the one-knob version proves the shape.

Context​

The theme renders a classic title header on ordinary pages, with a per-page Hide the page title checkbox (Page Settings). A header/footer batch added a global default — pages_show_title_on_builder, shipping as yes — that extended a title-only H1 header to builder pages too, motivated by the heading-outline audit (every page should have exactly one H1). The immediate effect: existing builder-built sites (the marketing home, the demos hub) suddenly grew a duplicate title bar above their heroes.

Options considered​

• Keep showing by default — guarantees an H1 on builder pages whose authors forgot one, but breaks every existing designed page and duplicates the H1 on every page that does have a hero heading (the normal case).
• Hard-disable on builder pages — the Bricks/Oxygen philosophy: a built page owns its markup, the checkbox becomes classic-editor-only. Simplest, but removes the option for docs-style sites that genuinely want a uniform title bar above builder content.
• Hide by default, keep the opt-ins (chosen) — flip the global default to no; the site-wide toggle remains for uniform-title-bar sites, and the per-page checkbox still force-hides when the global is on.

Decision​

Builder pages hide the theme title by default. pages_show_title_on_builder defaults to no (declaration and code fallback both), the global toggle stays available as a site-wide opt-in, and the per-page Hide the page title checkbox keeps working everywhere — it is the control that matters on classic-editor pages, and it still wins on builder pages when the global is enabled.

Why​

Every major builder ecosystem treats the theme title as opt-out-by-design on built pages: Elementor's Canvas/Full-Width templates and starter kits ship with the title hidden, Divi and the Astra/GeneratePress/Kadence companion themes expose a per-page "Disable Title" that their starter sites pre-check, and Bricks/Oxygen render no theme title at all. The common thread is that a builder page is a designed composition whose hero supplies its own H1 — injecting the theme title above it duplicates headings and defaces the design, which is exactly what happened to the existing sites. The one-H1 accessibility goal is better enforced by the ship-gate checklist (the hero must contain the H1) than by forcing a title bar onto every built page. Flipping one default restored every existing site without editing a single page, and no capability was lost: both the global and per-page controls survive.

Context: with Motion = Scroll-scrub, the gallery owned only the ~1–1.5 viewport-heights of scroll it took to pass through the viewport — a ring turned ~90° and was gone, so visitors barely registered that they were driving it. At the same time the Motion group had grown flat and confusing: Loop Duration applies only to Auto-rotate, the incoming pin controls only to Scroll-scrub, On Hover only to Auto — all stacked together with no hint of what applied when. And the framework carries a documented scar here: converting a saved scalar option to a multi-picker array previously corrupted the options-render AJAX and produced the blank "error:" modal on pre-existing items (the easing-options incident).

Options considered:

• Pinning: scroll-hijack JS vs CSS position: sticky. Hijacking (wheel interception) gives exact control but breaks native momentum, accessibility and mobile feel. CSS sticky — wrapper stretched to stage + N × 100vh, stage stuck viewport-centred inside it — keeps native scrolling, degrades to the old pass-through when unsupported, and needs only a progress-formula change in the shared driver.
• Motion UI: flat group with better labels vs a nested multi-picker. Labels don't scale — every new mode multiplies the irrelevant-slider pile. A multi-picker reveals per-mode settings, but had never been nested inside another multi-picker (the Design picker) before; verification showed both the PHP (render + value round-trip) and the JS (instance-scoped > .choice-group selectors, pickerDescriptor.el === optionDescriptor.el filtering, lazy data-options-template injection re-firing fw:options:init) handle nesting, provided choice keys never collide across levels.
• Migration: reuse the drive key with JS+PHP migrators vs a NEW motion key. Reusing the key re-enters the easing-options failure class and demands a custom builder-item JS migrator. A new key means existing saves simply have nothing there — the picker renders its default and the illegal-string-offset path is unreachable; the views fall back to the legacy flat keys so saved galleries keep behaving identically on the front end.

Decision: both. Scroll-scrub gained Pin while scrubbing (default on) + Scroll Length (viewports), implemented as CSS sticky in the shared layer so every design — current and future — inherits it. Motion became an inline multi-picker (Auto/Continuous → loop/direction/hover; Scroll-scrub → pin/length/direction; Static → nothing) stored under the new motion key, with Drag to spin + Drag Momentum kept outside the picker because they layer over every mode.

Why: pinning is what makes scroll-scrub legible — the visitor holds the scene and feels the scroll steering it, which is the entire point of the mode. The nested picker keeps the Motion UI truthful (you only see what the chosen mode uses) and scales as designs and modes accumulate. The new-key strategy was the decisive safety call: it converts a historically dangerous value-shape migration into a no-op, at the negligible cost that pre-picker saves show the default Motion in the modal until re-saved. Doing it days after the gallery shipped — before real saves accumulate — made this the cheapest moment the change will ever have.

Context: multi-upload has no per-item fields, and the gallery's whole content model reads per-image data (alt, caption, title, description) from the Media Library. The click action had only Lightbox / Do Nothing.

Options considered:

• An order-matched URL list (addable rows beside the images) — breaks silently the moment images are reordered or removed; two lists pretending to be one.
• Abusing the attachment Description field as a URL — collides with Caption Source, which already offers Description as caption text.
• Restructuring Images into an addable-box of {image, link} — per-item fields, but a breaking value-shape change to the images option and a worse multi-image picking UX.
• A "Link URL" field on the attachment itself — attachment_fields_to_edit/_save puts a field in the media modal under Alt/Caption, stored as _upw_link_url meta.
• For the portfolio case specifically: a Post Type source — cards built from a post type's featured images, link = permalink, no per-image config at all.

Decision: both ends. The link lives on the attachment (_upw_link_url via the media-modal field), read when On Card Click = Open Link, with external hosts auto-opening a new tab (the tag_list convention) and alt falling back caption → title so linked cards always have an accessible name. And the Content tab gained a Source picker (Media Library | Post Type — a NEW key, so old saves are untouched and images keeps its original path): the Post Type choice lists public types with featured-image support dynamically, so Portfolio appears when that extension is active with no hard dependency, and each card links to its post automatically.

Why: the URL belongs to the image, in the same place its caption and alt already live — it follows the image wherever it is reused, survives reordering, and is edited through the builder's normal "Edit image" flow (the media-replaceability rule). And the strongest use case for per-card links — "my portfolio, linked" — is better served by not entering URLs at all: the Post Type source derives cards and links from content that already exists, and stays fresh as posts are published.

Context​

The effect came from replicating a cinematic product site whose search moment scatters file cards across a photographic desk. Nothing in the framework matched: the core Gallery's designs (grid, masonry, carousel, coverflow) are arrangements; sticky-stack's messy is a pinned scroll stack; image_box's polaroid frame is a static card. The scatter is defined by its choreography — stagger-in, rest, sweep-out, cycle.

Options considered​

• A 21st core Gallery design — "it's where users look for galleries", always available (engine-off). But the core Gallery has no animation runtime: it would need the rAF driver, drag plumbing and reduced-motion handling duplicated from the 3D Gallery — exactly the parallel-machinery smell the CATALOG distinctness rule exists to prevent. And its designs would then split into two kinds (static vs choreographed) inside one picker.
• A new design of [gallery_3d] (chosen) — the 3D Gallery is the choreography line: a categorized Design picker where each design is a self-contained motion system over one shared rAF driver, with drag physics, per-card Box Styles, captions/lightbox/link plumbing, and "Use as Section Background". Its picker taxonomy had already reserved a Stack & Scatter category; Photo Scatter is its first occupant.

Decision​

photo_scatter shipped as a [gallery_3d] design (engine 1.2.36), not a core Gallery layout.

Why​

• The test is one question: "is it still a design if nothing moves?" A static scatter is just overlapping polaroids — the motion IS the design. Anything failing that test is choreography and belongs to the 3D Gallery; anything passing it (a grid, a justified layout) is an arrangement and belongs to the core Gallery.
• Machinery gravity. The 3D Gallery already owns everything the scatter needs — server-side card rendering (links/captions ride each card), the generation-guarded rAF runtime, Section Background mode, reduced-motion fallback. Zero duplication.
• Engine-gating is product separation, not a loss. Cinematic showcases are the Animation Engine's line; the core Gallery stays lean and always-available. Degradation is graceful either way (reduced motion = a static scatter; content is never lost).
• The boundary rule keeps future proposals from re-litigating this: file by the one-question test.