@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/hyperframes-motion-director/references/asset-choreography-and-render-qa.md

@@ -1,185 +0,0 @@
-# Asset Choreography And Render QA
-
-Use this reference when a user supplies a visual reference, asks for richer visual materials, or reports overlap, overflow, weak contrast, transparency, crop, or export differences.
-
-## Why This Gate Exists
-
-Three false positives repeatedly create avoidable rework:
-
-1. File count is mistaken for visual range.
-2. A named style is mistaken for the exact reference.
-3. Browser snapshots are mistaken for final rendered evidence.
-
-The correct unit of quality is a visible story action that survives export.
-
-## 1. Inspect The Exact Reference
-
-Resolve the source before interpreting it:
-
-- Attachment or pasted prompt: read the full local source.
-- Local repository or directory: inspect that exact path, not a similarly named remote project.
-- Image: inspect the pixels, not only the filename or style label.
-- Named style without an attachment: record the house interpretation and its uncertainty.
-
-Write the result into `asset_analysis.style_reference`:
-
-- `source_type`
-- `exact_source`
-- `reviewed`
-- `visual_grammar`
-- `narrative_boundary`
-- `forbidden_drift`
-
-`visual_grammar` contains observable properties, not praise words. Prefer:
-
-- Palette and ink/material behavior.
-- Edge, crop, outline, grain, halftone, shadow, and depth treatment.
-- Composition density and dominant-mass placement.
-- Relationship between type, image, and negative space.
-- Transition behavior implied by the material.
-
-Reject vague entries such as "premium", "advanced", "cinematic", or "Riso-like" unless they are followed by visible properties from the exact source.
-
-## 2. Separate Style From Story
-
-Define two independent contracts:
-
-- Style contract: how surfaces, edges, colors, materials, depth, and transitions look.
-- Narrative contract: which product actions, source claims, characters, objects, and proof states the viewer must understand.
-
-The style contract may transform the narrative objects. It may not replace them.
-
-Examples:
-
-- Riso can control ink colors, halftone, paper, registration offset, and wipes. It must not turn a publishing workflow into a film about printing machinery.
-- Collage can control torn edges, taped layers, paper depth, and assembly. It must not replace product proof with decorative stationery.
-- Cinematic black can control lighting, contrast, and pacing. It must not reduce a product promo to titles on a dark background.
-
-## 3. Build Assets By Motion Job
-
-Start from source nouns and verbs, then assign each accepted foreground component one or more motion jobs.
-
-Required jobs for premium multi-scene work:
-
-| Job | Question | Typical evidence |
-| --- | --- | --- |
-| Narrative anchor | What remains recognizably the same across beats? | person, article, hero object, product surface |
-| Product proof | What makes the claim visible and believable? | command, screenshot, state, result, number, choice |
-| Transition carrier | What physically carries material into the next beat? | tear, fold, route, wipe, stamp, rail, scan, fan |
-
-Additional source-derived jobs are allowed, such as counterweight, depth frame, inspection mark, or CTA resolver. They do not replace the three core jobs.
-
-The minimum of three independent foreground components for premium multi-scene work is mathematical, not stylistic: it is the smallest library that can form two distinct two-object combinations.
-
-## 4. Combination Proof
-
-Before animation, record at least two distinct combination tests for premium multi-scene work:
-
-```json
-{
-  "id": "article-to-preview",
-  "scene_id": "preview",
-  "component_ids": ["article-paper", "phone-frame", "scan-rail"],
-  "choreography": "The article folds into the phone while the scan rail confirms the preview state.",
-  "snapshot_timestamp": 11.4,
-  "deletion_test": "Without the phone or rail, the viewer cannot see that the same article became a checked preview."
-}
-```
-
-A valid second test changes the component set and the relationship between objects. These do not count:
-
-- The same cards with different labels.
-- The same component set at another timestamp.
-- Independent fade-ins with no handoff or shared action.
-- A decorative pile that does not prove a claim or bridge a scene.
-
-## 5. Composite Ownership
-
-A composite component is one semantic object even when implemented with many layers.
-
-Examples:
-
-- Terminal shell + command text + cursor + status light.
-- Search field + query + icon + border.
-- Product card + title + metadata + image + shadow.
-- Paper ring + logo + highlight + texture.
-
-All children share one owner for:
-
-- Transform.
-- Opacity.
-- Clip or mask.
-- Occlusion and stacking.
-
-If the shell goes behind a paper, its text and controls go behind the paper with it. A child may animate internally, but it may not cross the owner's external occlusion boundary.
-
-Record every risky group in `render_qa_contract.composite_groups`.
-
-## 6. Visible Alpha Bounds
-
-Transparent PNG placement must use the visible subject, not the file canvas.
-
-For every transparent asset aligned to text, a frame, a safe zone, or another object:
-
-1. Measure the smallest rectangle containing meaningful non-transparent pixels.
-2. Position and clear the asset from that visible rectangle.
-3. Preserve outer transparent padding for motion and filtering.
-4. Recheck the rendered frame after scale, perspective, and filter changes.
-
-This prevents a visually large transparent margin from making code coordinates appear correct while the visible paper, ring, or badge overlaps nearby text.
-
-## 7. Exported Text Fit
-
-Any narrow text container needs an export-parity check:
-
-- Search fields.
-- Pills and badges.
-- Buttons.
-- Small cards.
-- Terminal rows.
-- CTA labels.
-- Chinese/English mixed text.
-
-Measure with the font actually used by the renderer. If the renderer substitutes a font, use the exported width as the source of truth.
-
-Pass conditions:
-
-- Text remains inside the visible container, not only its CSS box.
-- Intended padding survives export.
-- No glyph clips at entry, hold, or exit.
-- Contrast remains readable over the exported background and opacity.
-
-## 8. Entry / Hold / Exit Evidence
-
-For each layered or text-rich scene, inspect three final-MP4 checkpoints:
-
-- Entry: ownership, clipping, initial overlap.
-- Hold: reading, contrast, font fit, visible bounds.
-- Exit: moving overflow, child desynchronization, transition collision.
-
-Each evidence row names:
-
-- Scene and phase.
-- Timestamp.
-- Rendered MP4 frame path.
-- Assertion.
-- Result.
-- Fix and rerun path when failed.
-
-Browser snapshots remain useful for fast iteration. They do not replace final-MP4 evidence.
-
-## 9. Failure Routing
-
-Fix the earliest faulty contract:
-
-| Failure | Update first |
-| --- | --- |
-| Style looks adjacent but not faithful | exact reference analysis and asset prompt |
-| Style mechanism hides the product | narrative boundary and storyboard |
-| Many assets still feel repetitive | motion-role coverage and combination tests |
-| Text floats through another object | composite ownership |
-| Transparent object overlaps nearby text | visible alpha bounds |
-| Browser fits but export overflows | exported font measurement and layout contract |
-| Hold looks good but motion clips | entry/exit checkpoints and motion bounds |
-
-After any fix, rerender the full affected path and re-extract the final MP4 frame. Do not close a render defect with browser-only evidence.

package/skills/hyperframes-motion-director/references/audio-sync.md

@@ -1,83 +0,0 @@
-# Audio Sync
-
-Use this reference when a video mentions music, beat hits, voiceover, captions, sound design, or rhythmic motion.
-
-## Principle
-
-Major visual events should land on intentional audio or rhythm moments. Minor visual texture may react to audio. Keep the main story independent from uncontrolled audio analysis.
-
-## Beat Map
-
-Create `BEAT_MAP.json` for music-synced or tightly timed videos.
-
-Include:
-
-- `fps`
-- `duration_seconds`
-- `audio_source`
-- `beats`
-- `hits`
-- `scene_ranges`
-- `snapshot_times`
-- `notes`
-
-Manual beat maps are acceptable. Claim waveform analysis only when it actually happened.
-
-## Structural Hits
-
-Use hits for:
-
-- First title impact.
-- Product reveal.
-- Proof/stat reveal.
-- Scene transition.
-- CTA lockup.
-
-Avoid placing every word on a hit. That feels mechanical and removes breathing room.
-
-## Voiceover Timing
-
-If voiceover exists:
-
-- Script first.
-- Generate or import audio.
-- Transcribe or manually time phrases.
-- Use phrase timestamps as scene boundaries.
-- Keep on-screen text shorter than spoken text.
-
-If transcription is unavailable, use manual phrase timing and mark it as an assumption.
-
-## Captions
-
-Caption-led videos need readability first:
-
-- Keep caption chunks short.
-- Avoid putting captions over busy product UI.
-- Keep caption position stable unless movement is part of the design.
-- Keep caption animation below the point where readability suffers.
-
-## Micro-Reactivity
-
-Audio-reactive motion is useful for:
-
-- Subtle glow.
-- Background texture.
-- Small scale pulse.
-- Light opacity breathing.
-
-Keep it away from:
-
-- Main copy timing.
-- Scene duration.
-- CTA readability.
-- Product reveal timing.
-
-## Sync Review
-
-Review in three passes:
-
-1. Silent pass: can the story be followed without audio?
-2. Audio pass: do major events land with the track?
-3. Frame pass: are hit frames readable rather than just flashy?
-
-If a beat lands while the frame is unreadable, the timing fails.

package/skills/hyperframes-motion-director/references/design-engineering.md

@@ -1,156 +0,0 @@
-# Design Engineering
-
-Use this reference when upgrading a HyperFrames motion project from taste guidance to repeatable production behavior.
-
-## Motion Design Compiler
-
-The skill should behave like a small Motion Design Compiler:
-
-```text
-brief -> scene schema -> vector templates -> motion primitives -> GSAP timeline -> browser snapshots -> render
-```
-
-Natural language names the direction. The compiler contracts preserve it.
-
-The compiler has four hard responsibilities:
-
-- Turn the storyboard into a scene schema with explicit slots, layout contracts, and beat timing.
-- Select approved vector templates instead of inventing new SVG geometry for every video.
-- Select legal motion primitives with semantic reasons and rejection tests.
-- Run render validation before final video export.
-
-## Required Production Contracts
-
-Every new production scaffold includes these files:
-
-- `SCENE_SCHEMA.json`: the structured scene contract for content, slots, layout, timing, motion, and snapshots.
-- `VECTOR_TEMPLATES.json`: approved SVG composition families and their slots, geometry rules, icon/decor rules, and rejection tests.
-- `MOTION_PRIMITIVES.json`: approved GSAP/SVG/CSS motion primitives, their semantic use cases, required parameters, and failure modes.
-
-These files are not optional polish. They reduce random generation.
-
-## Scene Schema
-
-The scene schema is the bridge between direction and implementation.
-
-Each scene must declare:
-
-- `template_id`: one approved vector template.
-- `content_slots`: title, support, proof, data, icon, CTA, or empty.
-- `layout_contract`: textRect, subjectRect, title tier, safeBottomY, motion bounds, and quiet zone.
-- `support_assets`: decision, roles, source, style lock, safe zones, motion purpose, entrance/exit timing, and deletion trigger.
-- `primitive_chain`: the approved motion primitives used by the scene.
-- `selection_reason`: why each primitive fits the meaning of the beat.
-- `readable_hold`: start and end timestamps for text stillness.
-- `snapshot_tests`: hero frame, transition midpoint, overflow check, and CTA lock.
-
-If a scene cannot be represented as structured data, it is not ready for implementation.
-
-## Vector Templates
-
-Start with a small approved set:
-
-- `quote_card`: huge claim or quote, minimal support line, one accent path.
-- `data_point`: one number or fact, proof label, counter or path emphasis.
-- `comparison`: before/after or tension/resolution, split axis, shared transition rail.
-
-Each vector template must define:
-
-- Slots and maximum text density.
-- Fixed layout zones and safe margins.
-- Allowed icon/decor roles.
-- Support asset policy for whether symbols, textures, transition plates, semantic glyphs, product fragments, or motion accents are allowed.
-- SVG parts that can animate.
-- Disallowed uses.
-- Snapshot acceptance rules.
-
-Do not let the LLM freely invent SVG geometry for production frames. It may choose and fill approved templates.
-
-Support assets must not bypass this rule. Code-generated paths, masks, glyphs, rails, and marks belong in the vector template system when they need sharp synchronized motion. Bitmap support assets require a declared role, local path after generation, safe zones, motion purpose, and deletion trigger.
-
-## Motion Primitives
-
-Use motion primitives as the legal animation vocabulary.
-
-The first set:
-
-- `maskReveal`: reveal a title, claim, subject, or CTA through a mask.
-- `pathDraw`: draw a connector, underline, route, signature, proof trace, or logo stroke.
-- `clipWipe`: move between scenes using a clipPath or mask edge.
-- `staggerText`: reveal a short keyword chain while preserving readable holds.
-- `numberCount`: animate a data value with a crisp proof lock.
-
-Every primitive must include:
-
-- Semantic use cases.
-- Required selectors.
-- Required timing fields.
-- GSAP property guidance.
-- Snapshot midpoint requirements.
-- Rejection tests.
-
-Avoid primitives that exist only because they look exciting.
-
-## Selection Rules
-
-The project needs selection rules, not a bigger effects menu.
-
-- Use `maskReveal` when the concept is disclosure, reveal, proof, or emergence.
-- Use `pathDraw` when the viewer should follow a route, process, trace, signature, connection, or proof line.
-- Use `clipWipe` when one scene physically replaces another through an axis, rail, frame, or window.
-- Use `staggerText` only for short keyword chains. Do not stagger dense paragraphs.
-- Use `numberCount` only when a number is the proof object. Do not count decorative numbers.
-
-If two primitives could work, choose the one with the clearer semantic role and lower visual noise.
-
-## Layout Engine Requirements
-
-Chinese text must be measured in the browser before render.
-
-Required checks:
-
-- Text bounding box stays inside `textRect`.
-- Optical vertical center is within the configured tolerance.
-- Title tier matches line count and character count.
-- Mixed Chinese/English terms do not overflow.
-- CTA and support text stay above `safeBottomY`.
-- Motion paths do not move readable text through unsafe top, right, or bottom zones.
-
-Markdown layout contracts are not enough. Final implementation needs measured geometry.
-
-## Render Validation
-
-Render validation must inspect frame output, not only files.
-
-At minimum, capture:
-
-- First frame.
-- Each hero frame.
-- Each transition midpoint.
-- Each data/proof lock.
-- CTA lock.
-
-Reject the production if:
-
-- Important text is clipped, off-center, or outside safe zones.
-- A transition midpoint is blank or visually accidental.
-- Motion is only opacity plus y-position for all important beats.
-- SVG exists only as decoration and does not carry structure.
-- Icons or decorative marks do not have a semantic role.
-- The video loses no important meaning when reduced to screenshots.
-
-## 100-Point Design Engineering Gate
-
-Use this score before final delivery:
-
-| Category | Points |
-| --- | ---: |
-| Scene schema filled with valid slots, layout contracts, and timing | 15 |
-| Approved vector templates used without ad hoc SVG geometry | 15 |
-| Chinese text measurement and safe-zone checks pass | 20 |
-| Motion primitives selected by semantic rules | 15 |
-| Mask/clipPath/path/SVG structure participates in transitions | 15 |
-| Browser snapshots inspect hero frames and transition midpoints | 15 |
-| Batch repeatability is preserved through structured data | 5 |
-
-Below 90 blocks final delivery. Below 75 means the project is still a prompt-driven draft.

package/skills/hyperframes-motion-director/references/gsap-choreography.md

@@ -1,202 +0,0 @@
-# GSAP Choreography
-
-Use this reference when a HyperFrames production needs premium motion, not just movement. It adapts GSAP Skills guidance for deterministic promo-video rendering.
-
-## First Principles
-
-Premium motion comes from controlled attention over time.
-
-GSAP choreography must decide:
-
-- What appears first.
-- What waits.
-- What bridges the next scene.
-- What becomes still for reading.
-- What motion would be missed if the video were reduced to screenshots.
-
-Use GSAP as a timeline engine, not as a pile of independent tweens.
-
-## Timeline Contract
-
-Every implemented composition needs one master timeline.
-
-Required:
-
-- `gsap.timeline({ paused: true, defaults: { duration, ease } })`
-- timeline labels such as `hook`, `reveal`, `proof`, `cta`
-- position parameters for every important tween
-- nested scene timelines only when they are added to the master timeline
-- registration to HyperFrames control, usually `window.__timelines`
-
-Avoid chained `delay` values. Use timeline labels and position parameters so the edit is readable and maintainable.
-
-Good pattern:
-
-```javascript
-const tl = gsap.timeline({ paused: true, defaults: { duration: 0.6, ease: "power2.out" } });
-tl.addLabel("hook", 0)
-  .from(".title-mask", { clipPath: "inset(0 100% 0 0)", autoAlpha: 0 }, "hook")
-  .to(".accent-path", { strokeDashoffset: 0, duration: 0.8 }, "hook+=0.25")
-  .addLabel("proof", 2.4)
-  .to(".scene-hook", { autoAlpha: 0 }, "proof-=0.2")
-  .from(".proof-number", { y: 32, autoAlpha: 0 }, "proof");
-```
-
-## Core Tween Rules
-
-Use:
-
-- `gsap.to()`, `gsap.from()`, and `gsap.fromTo()` intentionally.
-- `gsap.set()` for deterministic initial state.
-- `autoAlpha` instead of raw opacity when elements should disappear from visibility.
-- transform aliases such as `x`, `y`, `xPercent`, `yPercent`, `scale`, `rotation`, and `svgOrigin`.
-- `immediateRender: false` when multiple `from()` or `fromTo()` tweens affect the same target/property later in a timeline.
-
-Avoid:
-
-- raw `transform` strings when GSAP transform aliases can express the movement.
-- layout properties such as `top`, `left`, `width`, `height`, `margin`, or `padding` for motion.
-- invalid ease names.
-- uncontrolled repeat loops in render timelines.
-
-## Plugin Registration
-
-Register each plugin once before use.
-
-This plugin registration rule is part of the production contract, not a styling preference.
-
-```javascript
-import { gsap } from "gsap";
-import { DrawSVGPlugin } from "gsap/DrawSVGPlugin";
-import { MorphSVGPlugin } from "gsap/MorphSVGPlugin";
-import { MotionPathPlugin } from "gsap/MotionPathPlugin";
-import { SplitText } from "gsap/SplitText";
-import { CustomEase } from "gsap/CustomEase";
-
-gsap.registerPlugin(DrawSVGPlugin, MorphSVGPlugin, MotionPathPlugin, SplitText, CustomEase);
-```
-
-All GSAP plugins are available from the public `gsap` npm package. Do not add private registry or old Club GSAP authentication instructions.
-
-## Premium Promo Primitives
-
-### SplitText
-
-Use SplitText when text itself is the hero.
-
-Use cases:
-
-- large Chinese hook reveal
-- word-by-word capability chain
-- line-by-line manifesto
-- CTA lockup entrance
-
-Rules:
-
-- Split only short, intentional copy.
-- Preserve readable holds.
-- Revert or clean up split structures when the environment requires it.
-- Do not split dense paragraphs.
-
-### DrawSVG
-
-Use DrawSVG for line-based proof and premium accents.
-
-Use cases:
-
-- logo stroke reveal
-- underline or scan rail
-- route/path/process trace
-- inspection bracket
-- proof connector
-
-Rules:
-
-- The path must guide attention or prove a relationship.
-- Stroke width must match the vector template system.
-- A midpoint snapshot must show an intentional partial draw.
-
-### MorphSVG
-
-Use MorphSVG when one idea visibly becomes another.
-
-Use cases:
-
-- problem shape morphs into solution symbol
-- rough note becomes clean decision artifact
-- scattered fragments become product mark
-- old workflow becomes new workflow
-
-Rules:
-
-- Morph only between visually compatible simplified paths.
-- Use `shapeIndex` when the morph twists.
-- Simplify SVG path complexity before blaming GSAP.
-- Do not use morphing as decorative magic.
-
-### MotionPath
-
-Use MotionPath when a visual object should physically carry attention.
-
-Use cases:
-
-- cursor travels along a workflow
-- scan dot follows a route
-- proof tick follows a connector
-- product tile rides a transition rail
-
-Rules:
-
-- Align the moving target to the path when appropriate.
-- Use `autoRotate` only when rotation clarifies direction.
-- A path follower should hand attention to the next scene, not wander.
-
-### CustomEase
-
-Use CustomEase for one signature motion moment.
-
-Use cases:
-
-- brand reveal snap
-- scan settle
-- title compression release
-- proof lock
-
-Rules:
-
-- Prefer built-in eases for ordinary movement.
-- Use one custom curve per video unless the design system requires more.
-- Name the custom ease and document what emotional beat it serves.
-
-## Performance
-
-Use performance as part of taste. Jank makes premium motion feel cheap.
-
-Rules:
-
-- Prefer transform aliases and `autoAlpha`.
-- Use `will-change` only for elements that actually animate.
-- Use stagger instead of many separate tweens with manual delays.
-- Do not create hundreds of overlapping tweens.
-- Batch layout reads before writes when measuring text.
-- Kill or avoid offscreen/inactive animations.
-
-## Reduced Motion
-
-For interactive previews or web surfaces, use `gsap.matchMedia()` and respect `prefers-reduced-motion`.
-
-For rendered videos, document whether reduced-motion is irrelevant because the output is a fixed video file. Do not silently copy web accessibility rules into render timelines where they do not apply.
-
-## Review Gate
-
-Reject GSAP implementation if:
-
-- important tweens are not on the master timeline
-- labels are missing
-- position parameters are replaced by delay chains
-- all reveals use only opacity plus y
-- SVG paths, masks, or clips do not participate in transitions
-- SplitText is used on dense copy
-- plugin usage is undocumented or unregistered
-- layout-heavy properties drive motion
-- transition midpoint snapshots are blank or accidental