Skip to content

Commit 262854c

Browse files
feat(sdk): stage 6 — arc path ops (setArcPath, updateArcSegment, removeArcPath)
Port arc path trio from recast to browser-safe acorn+MagicString writer. Add SDK op types and mutate.ts handlers for setArcPath / updateArcSegment / removeArcPath. Decompose buildMotionPathObjectCode into small sub-functions in gsapSerialize.ts to stay within fallow complexity thresholds. Tests verify acorn output re-parses to correct arcPath shape. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> Co-authored-by: Miguel Ángel <[email protected]>
1 parent a29a0c6 commit 262854c

7 files changed

Lines changed: 510 additions & 110 deletions

File tree

‎packages/core/src/parsers/gsapSerialize.ts‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -475,3 +475,80 @@ export function resolveConversionProps(
475475
: { ...anim.properties };
476476
return { fromProps: { ...(anim.fromProperties ?? {}) }, toProps };
477477
}
478+
479+
// ── Arc path serialization helpers (shared by recast + acorn writers) ─────────
480+
481+
function numericXY(props: Record<string, number | string>): { x: number; y: number } | null {
482+
const vx = props.x;
483+
const vy = props.y;
484+
return typeof vx === "number" && typeof vy === "number" ? { x: vx, y: vy } : null;
485+
}
486+
487+
export function extractArcWaypoints(anim: GsapAnimation): Array<{ x: number; y: number }> {
488+
const keyframeWps = (anim.keyframes?.keyframes ?? [])
489+
.map((kf) => numericXY(kf.properties))
490+
.filter((pt): pt is { x: number; y: number } => pt !== null);
491+
if (keyframeWps.length >= 2) return keyframeWps;
492+
const propX = anim.properties.x;
493+
const propY = anim.properties.y;
494+
if (typeof propX !== "number" && typeof propY !== "number") return keyframeWps;
495+
const destX = typeof propX === "number" ? propX : 0;
496+
const destY = typeof propY === "number" ? propY : 0;
497+
return [
498+
{ x: 0, y: 0 },
499+
{ x: destX, y: destY },
500+
];
501+
}
502+
503+
function autoRotateSuffix(autoRotate: boolean | number): string {
504+
if (autoRotate === true) return ", autoRotate: true";
505+
if (typeof autoRotate === "number") return `, autoRotate: ${autoRotate}`;
506+
return "";
507+
}
508+
509+
function cubicControlPoints(
510+
seg: ArcPathSegment,
511+
wp: { x: number; y: number },
512+
nextWp: { x: number; y: number },
513+
): string[] {
514+
if (seg.cp1 && seg.cp2) {
515+
return [`{x: ${seg.cp1.x}, y: ${seg.cp1.y}}`, `{x: ${seg.cp2.x}, y: ${seg.cp2.y}}`];
516+
}
517+
const dx = nextWp.x - wp.x;
518+
const dy = nextWp.y - wp.y;
519+
const c = seg.curviness ?? 1;
520+
return [
521+
`{x: ${wp.x + dx * 0.33}, y: ${wp.y + dy * 0.33 - c * Math.abs(dx) * 0.25}}`,
522+
`{x: ${wp.x + dx * 0.66}, y: ${wp.y + dy * 0.66 - c * Math.abs(dx) * 0.25}}`,
523+
];
524+
}
525+
526+
function buildCubicPathEntries(
527+
waypoints: Array<{ x: number; y: number }>,
528+
segments: ArcPathSegment[],
529+
): string[] {
530+
const entries = [`{x: ${waypoints[0]!.x}, y: ${waypoints[0]!.y}}`];
531+
for (let i = 0; i < segments.length; i++) {
532+
const nextWp = waypoints[i + 1]!;
533+
entries.push(...cubicControlPoints(segments[i]!, waypoints[i]!, nextWp));
534+
entries.push(`{x: ${nextWp.x}, y: ${nextWp.y}}`);
535+
}
536+
return entries;
537+
}
538+
539+
export function buildMotionPathObjectCode(config: {
540+
waypoints: Array<{ x: number; y: number }>;
541+
segments: ArcPathSegment[];
542+
autoRotate: boolean | number;
543+
}): string {
544+
const { waypoints, segments, autoRotate } = config;
545+
const arSuffix = autoRotateSuffix(autoRotate);
546+
if (segments.some((s) => s.cp1 && s.cp2) && waypoints.length >= 2) {
547+
const pathStr = buildCubicPathEntries(waypoints, segments).join(", ");
548+
return `{ path: [${pathStr}], type: "cubic"${arSuffix} }`;
549+
}
550+
const pathEntries = waypoints.map((wp) => `{x: ${wp.x}, y: ${wp.y}}`);
551+
const curviness = segments[0]?.curviness ?? 1;
552+
const curvPart = curviness !== 1 ? `, curviness: ${curviness}` : "";
553+
return `{ path: [${pathEntries.join(", ")}]${curvPart}${arSuffix} }`;
554+
}

‎packages/core/src/parsers/gsapWriter.parity.test.ts‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,20 @@ import {
2424
materializeKeyframesFromScript as materializeAcorn,
2525
splitIntoPropertyGroupsFromScript as splitGroupsAcorn,
2626
splitAnimationsInScript as splitAnimsAcorn,
27+
setArcPathInScript as setArcAcorn,
28+
updateArcSegmentInScript as updateArcSegmentAcorn,
29+
removeArcPathFromScript as removeArcAcorn,
2730
} from "./gsapWriterAcorn.js";
28-
2931
function acornId(script: string): string {
3032
const parsed = parseGsapScriptAcornForWrite(script) as ParsedGsapAcornForWrite;
3133
return parsed.located[0]!.id;
3234
}
3335

36+
function arcShapeOf(script: string) {
37+
const anim = parseGsapScript(script).animations[0]!;
38+
return { arcPath: anim.arcPath, properties: anim.properties };
39+
}
40+
3441
/** Reparse a written script and return the first animation's editable shape. */
3542
function shapeOf(script: string) {
3643
const anim = parseGsapScript(script).animations[0]!;
@@ -390,3 +397,66 @@ describe("parity: splitAnimationsInScript (recast vs acorn)", () => {
390397
expect(splitAnimsAcorn(script, opts).script).toBe(script);
391398
});
392399
});
400+
401+
// ─── arc path parity ──────────────────────────────────────────────────────────
402+
403+
const ARC_FLAT_SCRIPT = `
404+
const tl = gsap.timeline({ paused: true });
405+
tl.to("#hero", { x: 100, y: 50, duration: 2 }, 0);
406+
`;
407+
const ARC_CFG = {
408+
enabled: true as const,
409+
autoRotate: false as const,
410+
segments: [{ curviness: 1 }],
411+
};
412+
const DISABLE_CFG = {
413+
enabled: false as const,
414+
autoRotate: false as const,
415+
segments: [] as never[],
416+
};
417+
418+
function arcFixture() {
419+
const id = acornId(ARC_FLAT_SCRIPT);
420+
const enabled = setArcAcorn(ARC_FLAT_SCRIPT, id, ARC_CFG);
421+
return { id, enabled };
422+
}
423+
424+
describe("setArcPathInScript: acorn output correctness", () => {
425+
it("enable: arcPath.enabled=true, segments preserved", () => {
426+
const id = acornId(ARC_FLAT_SCRIPT);
427+
const shape = arcShapeOf(setArcAcorn(ARC_FLAT_SCRIPT, id, ARC_CFG));
428+
expect(shape.arcPath?.enabled).toBe(true);
429+
expect(shape.arcPath?.segments).toHaveLength(1);
430+
});
431+
432+
it("disable: arcPath=undefined, x/y restored", () => {
433+
const { id, enabled } = arcFixture();
434+
const shape = arcShapeOf(setArcAcorn(enabled, id, DISABLE_CFG));
435+
expect(shape.arcPath).toBeUndefined();
436+
expect(typeof shape.properties.x).toBe("number");
437+
});
438+
439+
it("no-op when animation not found", () => {
440+
expect(setArcAcorn(ARC_FLAT_SCRIPT, "nope", ARC_CFG)).toBe(ARC_FLAT_SCRIPT);
441+
});
442+
});
443+
444+
describe("updateArcSegmentInScript: acorn output correctness", () => {
445+
it("curviness update reflected in parsed shape", () => {
446+
const { id, enabled } = arcFixture();
447+
const shape = arcShapeOf(updateArcSegmentAcorn(enabled, id, 0, { curviness: 2 }));
448+
expect(shape.arcPath?.segments[0]?.curviness).toBe(2);
449+
});
450+
451+
it("no-op when index out of range", () => {
452+
const { id, enabled } = arcFixture();
453+
expect(updateArcSegmentAcorn(enabled, id, 99, { curviness: 2 })).toBe(enabled);
454+
});
455+
});
456+
457+
describe("removeArcPathFromScript: acorn output correctness", () => {
458+
it("arcPath=undefined after removal", () => {
459+
const { id, enabled } = arcFixture();
460+
expect(arcShapeOf(removeArcAcorn(enabled, id)).arcPath).toBeUndefined();
461+
});
462+
});

‎packages/core/src/parsers/gsapWriterAcorn.ts‎

Lines changed: 165 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,17 @@
77
* pretty-printer churn. Consumes ParsedGsapAcornForWrite from gsapParserAcorn.ts.
88
*/
99
import MagicString from "magic-string";
10-
import type { GsapAnimation, GsapPercentageKeyframe } from "./gsapSerialize.js";
11-
import { resolveConversionProps } from "./gsapSerialize.js";
10+
import type {
11+
GsapAnimation,
12+
GsapPercentageKeyframe,
13+
ArcPathConfig,
14+
ArcPathSegment,
15+
} from "./gsapSerialize.js";
16+
import {
17+
resolveConversionProps,
18+
extractArcWaypoints,
19+
buildMotionPathObjectCode,
20+
} from "./gsapSerialize.js";
1221
import {
1322
parseGsapScriptAcornForWrite,
1423
type ParsedGsapAcornForWrite,
@@ -1304,6 +1313,160 @@ export function removeLabelFromScript(script: string, name: string): string {
13041313
return ms.toString();
13051314
}
13061315

1316+
// ── Arc path helpers ─────────────────────────────────────────────────────────
1317+
1318+
/**
1319+
* Remove a set of properties from an ObjectExpression in a single pass.
1320+
* Groups consecutive marked props into blocks to avoid overlapping remove ranges.
1321+
*/
1322+
function removePropsByKey(ms: MagicString, objNode: any, keys: Set<string>): void {
1323+
if (objNode?.type !== "ObjectExpression") return;
1324+
const allProps = (objNode.properties ?? []).filter(isObjectProperty);
1325+
const marked = allProps.map((p: any) => keys.has(propKeyName(p) ?? ""));
1326+
let i = 0;
1327+
while (i < allProps.length) {
1328+
if (!marked[i]) {
1329+
i++;
1330+
continue;
1331+
}
1332+
const blockStart = i;
1333+
while (i < allProps.length && marked[i]) i++;
1334+
ms.remove(...blockRemoveRange(allProps, blockStart, i));
1335+
}
1336+
}
1337+
1338+
function blockRemoveRange(allProps: any[], blockStart: number, blockEnd: number): [number, number] {
1339+
if (blockStart === 0 && blockEnd === allProps.length)
1340+
return [allProps[0].start, allProps[allProps.length - 1].end];
1341+
if (blockStart === 0) return [allProps[0].start, allProps[blockEnd].start];
1342+
return [allProps[blockStart - 1].end, allProps[blockEnd - 1].end];
1343+
}
1344+
1345+
// fallow-ignore-next-line complexity
1346+
function readLastWaypointXY(mpVal: any): { x: number | null; y: number | null } {
1347+
if (mpVal?.type !== "ObjectExpression") return { x: null, y: null };
1348+
const pathProp = findPropertyNode(mpVal, "path");
1349+
if (pathProp?.value?.type !== "ArrayExpression") return { x: null, y: null };
1350+
const elems: any[] = pathProp.value.elements ?? [];
1351+
const last = elems[elems.length - 1];
1352+
if (last?.type !== "ObjectExpression") return { x: null, y: null };
1353+
const xRaw = findPropertyNode(last, "x")?.value?.value;
1354+
const yRaw = findPropertyNode(last, "y")?.value?.value;
1355+
return { x: typeof xRaw === "number" ? xRaw : null, y: typeof yRaw === "number" ? yRaw : null };
1356+
}
1357+
1358+
function disableArcPath(ms: MagicString, call: TweenCallInfo): boolean {
1359+
const mpProp = findPropertyNode(call.varsArg, "motionPath");
1360+
if (!mpProp) return false;
1361+
const { x, y } = readLastWaypointXY(mpProp.value);
1362+
if (x === null && y === null) {
1363+
const allProps = (call.varsArg.properties ?? []).filter(isObjectProperty);
1364+
removeProp(ms, mpProp, allProps);
1365+
return true;
1366+
}
1367+
// Overwrite the entire motionPath property with the recovered x/y pair — avoids
1368+
// the appendLeft+remove range-boundary issue in MagicString.
1369+
const parts: string[] = [];
1370+
if (x !== null) parts.push(`x: ${x}`);
1371+
if (y !== null) parts.push(`y: ${y}`);
1372+
ms.overwrite(mpProp.start, mpProp.end, parts.join(", "));
1373+
return true;
1374+
}
1375+
1376+
function stripXYFromKeyframes(ms: MagicString, kfPropNode: any): void {
1377+
if (kfPropNode?.value?.type !== "ObjectExpression") return;
1378+
const xyKeys = new Set(["x", "y"]);
1379+
for (const pctProp of (kfPropNode.value.properties ?? []).filter(isObjectProperty)) {
1380+
const k = propKeyName(pctProp);
1381+
if (typeof k === "string" && k.endsWith("%") && pctProp.value?.type === "ObjectExpression") {
1382+
removePropsByKey(ms, pctProp.value, xyKeys);
1383+
}
1384+
}
1385+
}
1386+
1387+
function enableArcPath(
1388+
ms: MagicString,
1389+
call: TweenCallInfo,
1390+
animation: GsapAnimation,
1391+
config: ArcPathConfig,
1392+
): boolean {
1393+
const waypoints = extractArcWaypoints(animation);
1394+
if (waypoints.length < 2) return false;
1395+
const segments: ArcPathSegment[] =
1396+
config.segments.length === waypoints.length - 1
1397+
? config.segments
1398+
: Array.from({ length: waypoints.length - 1 }, () => ({ curviness: 1 }));
1399+
const motionPathCode = buildMotionPathObjectCode({
1400+
waypoints,
1401+
segments,
1402+
autoRotate: config.autoRotate,
1403+
});
1404+
upsertProp(ms, call.varsArg, "motionPath", `__raw:${motionPathCode}`);
1405+
stripXYFromKeyframes(ms, findPropertyNode(call.varsArg, "keyframes"));
1406+
removePropsByKey(ms, call.varsArg, new Set(["x", "y"]));
1407+
return true;
1408+
}
1409+
1410+
export function setArcPathInScript(
1411+
script: string,
1412+
animationId: string,
1413+
config: ArcPathConfig,
1414+
): string {
1415+
const parsed = parseGsapScriptAcornForWrite(script);
1416+
if (!parsed) return script;
1417+
const target = parsed.located.find((l) => l.id === animationId);
1418+
if (!target) return script;
1419+
const ms = new MagicString(script);
1420+
const handled = config.enabled
1421+
? enableArcPath(ms, target.call, target.animation, config)
1422+
: disableArcPath(ms, target.call);
1423+
return handled ? ms.toString() : script;
1424+
}
1425+
1426+
export function updateArcSegmentInScript(
1427+
script: string,
1428+
animationId: string,
1429+
segmentIndex: number,
1430+
update: Partial<ArcPathSegment>,
1431+
): string {
1432+
const parsed = parseGsapScriptAcornForWrite(script);
1433+
if (!parsed) return script;
1434+
const target = parsed.located.find((l) => l.id === animationId);
1435+
if (!target) return script;
1436+
1437+
const { call, animation } = target;
1438+
if (!animation.arcPath?.enabled) return script;
1439+
1440+
const segments = [...animation.arcPath.segments];
1441+
if (segmentIndex < 0 || segmentIndex >= segments.length) return script;
1442+
1443+
segments[segmentIndex] = { ...segments[segmentIndex]!, ...update };
1444+
1445+
const waypoints = extractArcWaypoints(animation);
1446+
if (waypoints.length < 2) return script;
1447+
1448+
const motionPathCode = buildMotionPathObjectCode({
1449+
waypoints,
1450+
segments,
1451+
autoRotate: animation.arcPath.autoRotate,
1452+
});
1453+
1454+
const mpProp = findPropertyNode(call.varsArg, "motionPath");
1455+
if (!mpProp) return script;
1456+
1457+
const ms = new MagicString(script);
1458+
ms.overwrite(mpProp.value.start, mpProp.value.end, motionPathCode);
1459+
return ms.toString();
1460+
}
1461+
1462+
export function removeArcPathFromScript(script: string, animationId: string): string {
1463+
return setArcPathInScript(script, animationId, {
1464+
enabled: false,
1465+
autoRotate: false,
1466+
segments: [],
1467+
});
1468+
}
1469+
13071470
// ── splitAnimationsInScript helpers ──────────────────────────────────────────
13081471

13091472
/** Overwrite the selector (first arg) of a tween call. */

0 commit comments

Comments
 (0)