스크립팅 개요

Guida에는 브라우저 자동화를 위한 스크립팅 환경이 내장되어 있습니다. 스크립트는 g.* API를 통해 페이지와 상호작용하고, 데이터를 관리하며, 워크플로를 구성합니다.

스크립트 엔진

세 가지 엔진을 사용할 수 있습니다.

JavaScript (ClearScript V8) - ES2024+, top-level await, native Promise, Chrome 및 Node.js와 같은 V8 엔진 기반 ES module import.
Lua (LuaCSharp) - 일반 Lua 문법, 테이블 중심 API, require()로 읽는 워크스페이스 라이브러리.
Janet (JanetSharp) - 불변 데이터 구조와 내장 PEG 엔진을 갖춘 함수형 Lisp 방언.

세 엔진은 같은 g.* API 표면을 공유합니다.

기본 형태와 top-level await

많은 자동화 작업은 비동기입니다. 조기 return이 필요 없는 스크립트에서는 Guida가 top-level await를 지원합니다.

const tabs = g.tabs.getTabs();
g.log("열린 탭: " + tabs.length);

중간에 종료하거나 return을 사용하려면 코드를 async function main()으로 감싸고 끝에서 await main();을 호출합니다.

F5 로 편집기 안의 스크립트를 실행합니다.

오류 처리

JavaScript와 Janet에서는 g.* 메서드가 값을 직접 반환하고 실패하면 예외를 던집니다.

try {
  await g.dom.click("#submit");
} catch (e) {
  g.log("클릭 실패: " + e.message);
  return;
}

Lua에서는 관용적인 여러 반환값(nil, error)을 사용합니다. 덕분에 개발 중 Visual Studio 디버거가 “처리되지 않은” 예외에서 멈추는 일이 줄어듭니다.

local success, err = g.nav.navigateToUrl("https://example.com")
if not success then
    g.log("오류: 탐색 실패: " .. err)
else
    g.log("페이지를 불러왔습니다")
end

비동기 메서드

JavaScript에서는 await를 사용합니다. Lua와 Janet에서는 엔진이 호출을 자동으로 기다립니다.

async function main() {
  await g.nav.navigateToUrl("https://example.com");
  await g.dom.waitForDomStable();
  const html = await g.page.getDom();
  g.log("페이지를 불러왔습니다. DOM 길이: " + html.length);
}

g.nav.navigateToUrl("https://example.com")
g.dom.waitForDomStable()
local html = g.page.getDom()
g.log("페이지를 불러왔습니다. DOM 길이: " .. #html)

(g.nav.navigateToUrl "https://example.com")
(g.dom.waitForDomStable)
(def html (g.page.getDom))
(g.log (string "페이지를 불러왔습니다. DOM 길이: " (length html)))

워크스페이스

스크립트는 현재 워크스페이스를 기준으로 실행됩니다. 워크스페이스에는 스크립트, 저장소, 큐, 검색 인덱스, 사용자 지정 도구, 도메인 설정을 둘 수 있습니다.

워크스페이스가 있으면 AI 에이전트에도 “이 프로젝트에서 무엇을 해도 되는지”를 명확히 전달할 수 있습니다. 자세한 내용은 워크스페이스를 참조하세요.

보완 파일 생성

Tools > Developer > Generate Scripting Support Files… 를 사용하면 현재 API에 맞는 TypeScript 정의, Lua/Janet 가이드, 워크스페이스 LLM 지시, TypeScript 작성용 scaffold를 생성할 수 있습니다.

g.generateApiDocs()는 TypeScript 전용 고급 헬퍼(advanced TypeScript-only helper)입니다. 일반적으로는 Generate Scripting Support Files 를 사용하세요.