editorbrain 0.34.0 → 0.35.0

package/skill/editorbrain-motion/references/motion-craft.md

@@ -1,79 +1,172 @@
 # Motion craft
 
-Read when designing, adapting or reviewing an animated scene with any method. These starting values come from EditorBrain's own code-drawn library scenes and a few reference analyses, not yet validated on customer projects or phones; sound was checked only as data. They are judgment, not a template, effects checklist or quality score. The user's current request, effective media/audio preferences (including reduced or disabled motion and on-screen text density), the output profile, the selected style's `effects.md`, the approved direction, brand tokens and readability measured in this output override every number; a value outside a range is a reason to look, not an automatic defect.
-
-Pixels are per 1080 px short side at 30 fps; scale with resolution and halve per-frame values at 60 fps. Drift is the scale or position change over a hold, as a percentage of the frame.
+Read when designing, adapting or reviewing animation. This is a method, not a house
+style or a template. It draws on the authored library and reference analyses;
+those examples do not validate every transfer to a customer's video. Use the
+same resolved snapshot, scene decisions and timing as montage and sound. Current
+user choices, required tokens, output, selected style and relevant inspected
+references govern the work. Reduced/disabled motion, quiet pacing and negative
+space can be deliberate. Do not turn one reference's numeric settings into
+requirements for everyone.
 
 ## Intent before look
 
-State four lines per meaningful shot before choosing a component, effect or palette:
-
-1. **Understand:** the sentence the viewer must get, with its real numbers.
-2. **Action:** the visible action that demonstrates it, such as an object performing the comparison.
-3. **Consequence:** what visibly changes because of it, in the same shot.
-4. **Exit:** the final state and what carries into the next shot.
-
-They sharpen the intention and action of the motion skill's shot description (entry, hold and exit still apply) and fit the [code motion](code-motion.md) record; they are not a schema. If the viewer would understand the sentence equally without the action, reconsider whether the motion is decoration and restage.
-
-Explanatory mechanism comes before surface treatment (palette, texture, glow); the selected style's own mechanisms still apply. For code/compositing, derive geometry, counters, labels, camera targets and cues from one data model ([code motion](code-motion.md) covers deterministic time) and recompute every figure. When a beat reads weak, change travel, scale, composition or timing before adding effects.
-
-**Honest data.** The data must demonstrate the claim (a difference of about 10 % or more, a threshold actually crossed) or the payoff changes; keep the before state credible. Map quantity to the visible dimension (area by √value), compare on one scale, clock and cost basis, and declare exaggerated or non-linear scales on screen. Leaders end at measured endpoints, emphasis follows the message target rather than the maximum, and data-dependent wording follows the computed values.
-
-## Starting values
-
-**Easing and springs.** No linear spatial motion: ease-out for entrances, in-out and arcs for travel; interpolate data values monotonically. Start springs from rest: no jump after a standstill (one fix capped that first step near 30 px) and no frame stepping several times its neighbors. A damping ratio ζ ≈ 0.8 gives about 1.5 % overshoot (convert to the engine's stiffness/damping/mass) over a 0.22–0.26 s main travel; large elements overshoot 2 % at most, and springs settle within their beat. Anticipate major moves with a 1–8 % counter-move (15–20 % for large rotations). Reveals take 0.18–0.45 s with a strong ease-out; related elements stagger 2–4 frames, secondary parts follow through 2–4 frames late, and edges on separate springs stretch and catch up. Squash only the hero, by 2 % at most. Large elements stay well under about 140 px per frame; above about 100 px per frame add directional blur (ghosts only on small objects, never over text). For exact endpoints, see [targeted motion review](../../editorbrain/references/motion-review.md).
-
-**Staging and holds.** One primary move and focal point at a time; dim the rest 40–60 % and start the next move at 80–90 % settled. Hold 0.4–0.8 s after intermediate payoffs and 1.5–2.5 s at the end of a standalone piece or before a hard end (under 1.2 s is a warning); a shot that hands off, or an insert under continuing voice, keeps its readable hold and designs its exit. Outside planned holds, over about 1 s with no readable change and nothing else carrying the beat (narration, action) is a dead-air candidate; keep holds alive with 0.5–2 % drift, never above 3 %, unless motion is reduced or disabled. Nothing appears, disappears or swaps for one unintended frame; deliberate cuts, stepped motion and reduced-motion states are exempt. Switch layers on time, never on a spring threshold. Keep full-frame flashes to three per second or fewer, timed in seconds; a count does not certify photosensitivity safety.
-
-**First and last frames.** Shots enter already in motion unless stillness is the design or motion is reduced. When the first frame may be seen alone (autoplay, preview, thumbnail), compose it with subject and title present. Do not reserve visible holes; bring later content in from an on-screen object or a motivated pull-back, and show an empty container only when its emptiness is the information (about 0.25–0.3 s). When a piece or beat closes, end on a designed state: scaffolding gone, deformations eased back.
-
-**Payoff.** Design a separate end-state layout, not the first layout minus elements: the answer at least as large as the setup figure, about twice its neighbors and legible at rest without a push. During action keep the protagonist near 25 % of frame height in 16:9 and 30–40 % in narrower ratios. A measuring gesture landing on the computed value makes a strong payoff; craft must not delay or shrink the answer.
-
-**Object-driven transitions.** Keep one protagonist and change its function: a row becomes a ticket, a total a stamp. Leave states accelerating: content out, container moves and settles, content in. Move the same object between layouts rather than fading one out and another in; replace busy crossfades and hue tweens with a wipe, mask or occluder starting at the cause. Causes precede effects: objects lead their labels, counters change when a visible carrier lands, a source shows the gap left behind, and a state a transition introduces persists until another removes it.
-
-**Camera.** Without style direction, push in on one subject and pull back to show the system; avoid moves that only add energy. Interpolate zoom in log space. Emphasis pushes start around 1.4–4.5 % and follows around 1.3–1.75×, lower in 9:16; if cropping would force a push below about 1.15×, dim the rest or scale the focal element instead. Pans stay under about 25 px per frame with continuous velocity and finish 0.15 s before cuts. At every hold, each label and title is wholly inside the safe margin or wholly off-frame; text that must not crop lives in screen space and crosses the frame edge only while moving. Start a beat once its element is framed.
-
-**Type as objects.** Unless the type is the action (kinetic type, beat-locked or word-synced words, line or letter mask reveals), move phrases or lines as blocks with one behavior each; text exits before its container moves and returns after it settles. Fit text at its final rendered size and font settings: shrink to the size floor (see Ratios), then two balanced lines, then a short alternate; never truncate a number. Same-role labels share the smallest fitted size, and anything placed or animated from a text block follows its measured line count. Size masks from measured ink with descender and accent room; test g, j, p, y, ¿, ¡, Á, É, Ñ and currency in the actual fonts, and never synthesize italics. Use tabular figures for changing numbers, one locale-aware formatter (no −0, singular and zero forms), no-break spaces before units, no orphaned units, and differences from the rounded values shown; rolling numbers show each value 0.25 s or more.
-
-**Text over imagery and color.** Choose the text color among the resolved brand text roles by measured contrast with the actual backdrop; if no permitted role passes, treat it as a project decision (see [component library](component-library.md)), never silent recoloring. Over footage or busy texture, small text gets a scrim, veil or knockout band, and HUD readouts or values in flight an opaque plate; a translucent plate must not show text behind it. Key text ends at 4.5:1 or more. Temporary dims, veils and ghosts exit before the hold; one accent per meaning. Derive shadows, highlights and flashes from the palette's luminance rather than fixed values.
-
-**Labels and drawn objects.** Place labels, stamps and resting props against everything printed (text, credit, HUD, moving props and their rest poses) at every beat and ratio. Anchor stamps to the object's drawn bounds, not a data level; no decorative impact covers primary text; leaders never cross text. Overlaps happen only in motion, for about 0.4 s or less. Name each hero object from a small grayscale still at its smallest size and ask what else it could be; give it defining cues (edge, binding, cap, sheen), one light direction and highlights that add light rather than desaturate; textures move with their object, and decorative strokes never look like data marks.
-
-**Copy and density.** About 3–4 words per beat, a new idea every 1.5–2 s, and each text fully visible 0.6 s plus 0.25 s per word beyond three; lengthen the shot, or cut copy when timing is locked to voice, rather than compress reading. These figures apply to graphic copy, not word-synced captions, and `onScreenText` sets the density. Leave 0.35 s between text events, let the outgoing line leave before the next enters, and give the last item of each sequence 0.4 s clean before a transition covers it. Individually read events need about 0.3 s each; when faster, or beyond about eight labeled items (about 35 anonymous tokens), show two or three slowly, then an aggregate. Text below the size floor is texture and carries no message. Scroll-first formats may need the answer within 1–2 s unless the brief's hook deliberately withholds it.
-
-**Sound-first timing.** When narration exists, lock it first (see [audio production](../../editorbrain/references/audio-production.md)) and anchor events to it; voice-synced text lands 0–5 frames after the word, never before (one measured reel). With SFX or music, derive cues from the motion's event list; for rhythmic or physical scenes without locked narration, a beat grid can lead, without every cut on a beat. Align each sample's measured peak or attack, not its file start: impacts on contact, whooshes at peak velocity, chimes and swells on the settle or resolve. Cluster trains above about 6–8 cues per second; gain follows magnitude. Respect exclusions; every SFX needs a visible cause, the scene must read muted, and aligned data still needs listening.
-
-**Ratios.** Recompose graphic layers per ratio from one model with identical beat times instead of cropping another ratio's render; reframing footage or cropping an asset inside the layout is fine. In 9:16, transpose the main axis rather than shrink; no band over about 15–20 % of the height stays empty beyond about 1 s. Carry moves under about 40 px in secondary cues (lean, tension, counters); a protagonist leaving a system travels about a third of the frame height. No hero state is a sliver beyond about 0.5 s, text never rotates 90° to fit, key actions stay in frame, and narrow ratios get gentler camera moves. The size floor is a font size at final on-screen scale of about 20 px in 16:9 and 1:1 and 22 px in 9:16 and other portrait ratios: a floor, not a target, confirmed at delivery size. Take platform UI zones from the output profile or destination.
-
-## Failure modes
-
-| Failure | Detect with |
+For a meaningful shot, capture four answers in the existing direction or shot
+record; do not create a second plan:
+
+1. **Understand:** what the viewer must get, with the real words and numbers.
+2. **Action:** the visible behavior that explains it.
+3. **Consequence:** what changes because of that action.
+4. **Exit:** the readable result and what carries into the next beat.
+
+A mechanism comes before glow, palette or decoration. For an ambitious explanation,
+keep the inspected reference sequence and relevant implementation open while
+adapting its action. Reuse useful source code, geometry and timing utilities; alter
+the composition for this message and actual assets. A polished generic label reveal
+is not an equivalent of an example that demonstrates a process. Conversely, a
+simple reveal may be exactly right for a small identification cue.
+
+Derive geometry, counters, labels and cues from one data model. Recompute claims
+from the real values on a common unit/time/cost basis. Quantity encoded by area
+needs area-proportional geometry, not radius-proportional sizing. Small differences
+can matter: never change numbers or invent a minimum percentage to make an
+animation dramatic. Disclose non-linear/exaggerated scales if used. If the data
+does not support the claim, correct the claim or staging, not the facts.
+
+## Design the action
+
+**Timing and easing.** Choose the behavior for its meaning: eased travel for a
+settle, a controlled spring for a physical response, linear motion for a constant
+rate, or stepped motion for an intentional graphic language. Do not apply the
+same spring to every object. As a test value for a short, energetic entrance,
+try roughly 0.2–0.45 s and a small stagger, then compare with the reference,
+voice/action and delivery size. These are optional starting points, not limits.
+Check continuous velocity, exact rest states and unintended frame jumps. Avoid
+excessive overshoot or ghosting over readable text. Derive state from time rather
+than playback history; see [code motion](code-motion.md).
+
+**Staging.** Make the focal relationship clear. Simultaneous action, a grid or a
+quiet hold can all work when the viewer can follow them. Control hierarchy through
+placement, scale, contrast and occlusion rather than always dimming everything or
+adding a plate. Hold long enough to perceive the result at delivery size; shorten
+dead air that serves no voice, action or reading need. Do not add compulsory drift
+to every hold. Measure rapid state changes when they matter; avoid unintended
+flashes, pops or disappearing layers. A numeric flash count is not a photosafety
+certification.
+
+**Entry, payoff and exit.** Compose a meaningful first frame and a completed last
+state for the actual use: a standalone demo, an insert and a scene under continuous
+speech need different handles. A hook need not carry a title when the user wants
+clean footage. Show the answer clearly, without a prescribed size ratio or long
+outro pause. Empty space or an empty container is valid when it communicates the
+setup or leaves room for UI; accidental blanks are not. Remove leftover scaffolding
+and settle temporary deformation when the scene calls for a finished state.
+
+**Transitions and camera.** Choose cuts, masks, continuity moves, dissolves or
+object transformations according to the argument and style. When an object carries
+between scenes, match its identity, crop, anchor, bounds and state. Cause-and-effect
+animation must preserve logical order; objects should not claim to arrive before
+they do. A camera move should reveal detail, contrast or a system, not merely add
+energy. Check framing and readable states along the move, not only endpoints;
+essential labels must remain visible when they need to be read. Keep user footage
+and presenter treatment within the effective layout preference.
+
+## Typography, imagery and formats
+
+**Typography is part of the composition.** Use the actual resolved font files,
+weights and available italic faces. Fit the real copy at final scale, including
+accents, descenders, currency and locale formatting. Rewrap, recompose or shorten
+nonessential copy before making it too small. Never silently truncate a number,
+claim or required CTA. Size reveal masks from measured glyph bounds. Changing
+numbers can use tabular figures; align visible rounded values with the claim.
+
+Move phrases as blocks when they must be read together. Use word/letter choreography
+when kinetic type or spoken emphasis is the mechanism. Entrances and exits can
+contrast across beats without every line spinning, bouncing or blurring. Captions
+follow their actual word cues and language/treatment; graphic copy can anticipate
+or summarize speech when intentional. Text density is not subtitle frequency.
+Check the smallest important text on a phone-sized preview rather than relying
+on a universal pixel floor.
+
+**Text over images.** Inspect the actual changing backdrop. Use permitted brand
+text roles with sufficient contrast; try position, selective shading, outline or
+an appropriate plate according to style. No automatic opaque box, blanket blur or
+recoloring of authentic footage, skin, logos or UI. If required roles cannot remain
+legible, make a deliberate project decision under the shared precedence. Keep
+essential graphics clear of faces, captions and platform controls during motion
+and at rest. Decorative oversize/cropped type may be intentional; clipped essential
+words are defects.
+
+**Drawn objects.** Choose visual cues that make the object recognizable at its
+smallest delivered size. Texture and light should follow its shape and movement.
+Leaders, stamps and props should land on their intended target without hiding the
+message. Inspect their paths as well as rest poses. Distinguish decorative marks
+from quantitative marks. A real product demonstration needs authentic evidence;
+clearly illustrative UI is not proof of a product feature.
+
+**Formats.** Recompose graphic layers for each requested ratio using the same
+message and appropriate timing, not a cropped wide render. Adjust axes, line
+breaks, trajectory and asset crop. Portrait does not require filling every band;
+negative space and platform UI reserves may be necessary. Use output safe areas
+and the destination check in [production review](../../editorbrain/references/production-and-review.md).
+A wide pass does not validate vertical readability. Reduced-motion versions can
+use still states or restrained transitions without losing information.
+
+## Coordinate sound and timing
+
+[Audio production](../../editorbrain/references/audio-production.md) owns the timing
+anchor and mix: voice-led work uses final narration; music/action-led work can have
+secondary narration without switching anchors. Motion consumes the montage's
+current final timeline. If a shot's duration changes, retime dependent captions and
+sound cues rather than keeping old absolute seconds.
+
+When sound is chosen, expose meaningful events to the sound pass: contact, travel,
+reveal, resolution or narrative emphasis. Align the sample's attack or intended
+peak, not just its file start. Not every cut or word needs a sound; off-screen
+sound and ambience can be purposeful too. Respect protected hooks and independent
+music/SFX exclusions. A visual can carry a factual message without an SFX; a
+voice-led piece need not explain every spoken detail through graphic text alone.
+Listen to the encoded mix before claiming synchronization or audibility.
+
+## Review in proportion to risk
+
+| Question | Evidence to inspect |
 |---|---|
-| Text overflows, wraps badly or sibling sizes differ | Longest copy and maximum counts in every ratio |
-| Numbers contradict each other, the copy or the claim | Recompute derived figures and differences from visible operands |
-| Narrow ratios inherit the wide layout | Empty bands and margins on mid and last frames |
-| Labels, stamps or props land on text | Stills at every beat and rest pose in each ratio |
-| Moving values or labels cross text | Dense 10–30 fps strips over each flight |
-| Camera crops text at a hold | Label boxes against the safe margin at every hold |
-| Empty opening or unfinished ending | First and last frames alone at thumbnail size |
-| Rushed events or one-frame pops | Shortest event interval; frame-exact grids at state changes |
-| Dead air | Freeze scan, e.g. ffmpeg `freezedetect`, against planned holds |
-| Under-weighted payoff or misread object | One dominant element in the last seconds; grayscale silhouette at phone size |
-| Unmotivated effects | Glow, particles, blur-in or stock dashboard card without a cause |
-| Sound drifting from picture | Retime one event, compare cue and event frames, listen |
-| File size balloons | Size after the first render; unsettled motion tails, per-frame grain |
-
-Those effects are fine when the style, the user or a fitting component calls for them.
-
-## Self-review order
-
-1. Four lines, recomputed numbers, density arithmetic (count × interval fits the beat).
-2. Stills at every beat and mid-transition in each ratio, narrowest first, with zoomed crops of the smallest text.
-3. For parameterized or reused scenes, stress inputs: longest copy, extreme counts, descenders and accents, each applicable brand theme.
-4. Numeric checks where claims matter: text boxes, recomputed numbers, out-of-order seeks.
-5. Dense strips around transitions; every frame for events under 0.2 s.
-6. The whole export at delivery size, first and last frames included, listening to any audio.
-7. A fresh-context second pass, or a separate reviewer, on the final export's strips (tiles of 480 px or more, times inside the duration). Edge-cropped text is blocking; fix self-noted legibility or payoff weaknesses before reporting.
-8. Fix the cause (layout rule, data, timing) behind a defect; recheck that interval, the other ratios and the delivered whole.
-
-Record findings in the [code motion](code-motion.md) format and finish with [production and review](../../editorbrain/references/production-and-review.md). Clean engine diagnostics, where available, are necessary but not sufficient; passing checks is not artistic approval, and measured audio is not listened audio.
+| Does this retain the adopted mechanism and explain this beat? | Reference interval beside the actual passage, not only palette or component ID |
+| Are facts, text and hierarchy correct? | Recomputed values; longest copy and essential text at delivery size |
+| Do objects move and hand off coherently? | Adjacent frames/strips around transitions, paths, crops and mattes |
+| Are reading time, pace and continuity right? | Actual playback with the timing anchor; intentional holds distinguished from dead air |
+| Do preferences still hold in every output? | Resolved constraints against actual ratio, fonts, captions, layout and sound |
+| Did changes desynchronize something? | Updated cut map and dependent cue positions, then playback of the affected joins |
+
+For new reusable components, stress meaningful extremes: longest copy, changing
+counts, accents, selected palettes and each supported ratio. For temporal code,
+check important states after out-of-order seeks. For a localized text correction,
+reuse still-valid checks and inspect the affected layout/reading time; do not run
+every stress case again. Use dense strips only where fast motion needs them.
+
+Watch the final export and listen when that modality is available. A second review
+can help uncertain or complex work; it does not require a second agent, paid call
+or user approval on every edit. Record exact output/hash, interval, observed defect
+and correction using [code motion](code-motion.md). Fix the underlying cause,
+recheck affected events and the delivered whole. Uninspected audio or visuals stay
+unverified; technical checks are not artistic approval. Finish with the shared
+[production review](../../editorbrain/references/production-and-review.md).
+
+### V11 transfer guardrails
+
+For explanatory titles, animate a whole word or line through a measured mask by
+default. Do not split a normal word into independently displaced letters: the
+reader must not see accidental fragments such as “Ciberseguri da d”. Deliberate
+letter choreography remains an explicit editorial exception that must preserve
+readability throughout; a catalog example cannot override the user's direction.
+Use the optional [editorial primitives](component-library.md#editorial-primitives-next-release)
+for implementation, then fit to the actual brand, voice and scene. An approved
+example does not impose its palette, rhythm or montage on every user.
+
+Before delivery use the [full-video review sheet](../../editorbrain/references/local-production.md#full-video-sheet-and-social-ui-review-next-release),
+then inspect transitions and audio at finer resolution. Check important logos
+as protected boxes as well as text. Prefer increasing their readable size and
+moving them clear of platform UI over adding decorative objects. Use the
+full-montage matte contract when cutting out a presenter. A one-second stillness
+warning is diagnostic, not a requirement to animate every second of every genre.