@uiwwsw/hangulscript 0.4.0 → 0.6.0

package/LANGUAGE.md

@@ -1,97 +1,172 @@
-# 문장형 HangulScript v0.1 (실험판)
+# 한글스크립트 0.6 문법
 
-`.hgs`를 TypeScript로 변환한다. Python의 들여쓰기·단순한 함수·기본 함수를
-받아들이고, JS의 배열·객체·표현식과 TypeScript 타입을 활용한다.
-Python 소스 호환 언어나 임의의 한국어를 해석하는 AI 실행기가 아니다.
+문장형이 유일한 기본 문법입니다. 시작 표기 없이 첫 문장부터 작성합니다.
+키워드형과 `.ks` 입력은 제거됐습니다. 소스는 `.hgs`, 기본 빌드는 JavaScript와 `.d.ts`입니다.
+문장 블록은 공백 들여쓰기를 사용합니다. 탭과 여러 줄 표현식은 지원하지 않습니다.
+`#`로 시작하는 행은 주석입니다. 행 끝 주석은 지원하지 않습니다.
 
-## 문법
+## 값·함수·조건·반복
 
-파일 첫 줄 `문장으로 시작`으로 문장형을 명시하는 것을 권장한다.
-변수 선언·각 반복·함수 정의 문장으로도 자동 감지한다.
-기존 `.hgs` 키워드형은 계속 지원한다. 같은 파일 안에서는 하나의 방식을 사용한다.
-공백 들여쓰기 폭은 자유지만 같은 블록은 동일해야 하고 탭은 허용하지 않는다.
-`#`는 행 전체 주석이다. 문장 끝 주석은 현재 지원하지 않는다.
-
-```ks
-문장으로 시작
+```text
 이름은 "하늘"이다
-횟수는 3이다
+점수: 숫자는 90이다
+기준은 80으로 고정한다
 
-인사(누구)를 정의한다:
+인사(누구: 문자열)를 정의한다:
     돌려주기 "안녕, " + 누구
 
-각 순서를 범위(횟수)에서:
-    만약 순서 == 0 이라면:
-        출력("처음")
-    아니고 순서 == 1 이라면:
-        출력("다음")
-    아니면:
-        출력(인사(이름))
-
-동안 횟수 > 0:
-    횟수 = 횟수 - 1
-    만약 횟수 == 1 이라면:
+각 수를 범위(3)에서:
+    만약 수 == 1 이라면:
+        계속하기
+    출력(인사(이름), 수)
+
+동안 점수 < 100:
+    점수 = 점수 + 1
+    만약 점수 == 95 이라면:
         멈추기
 ```
 
-- 선언: `이름은 값이다` / `이름는 값이다`. 은·는은 문법적으로 둘 다 허용한다.
-  `let`으로 변환하며 재대입은 `이름 = 값`이다. 같은 범위에서 재선언할 수 없다. 빈 목록은 동적 목록 `any[]`로 생성한다.
-- 함수: `이름(인자)를 정의한다:`. 타입 없는 인자는 `any`로 변환한다.
-  `이름(인자: 문자열)를 정의한다:`처럼 타입을 명시할 수 있다.
-- 반환: `돌려주기 값`; 값 없이도 가능하다.
-- 조건: `만약 식 이라면:` / `아니고 식 이라면:` / `아니면:`.
-- 반복: `각 항목을 목록에서:`; 조사 을·를 모두 허용한다.
-- 조건 반복: `동안 식:`; `멈추기`, `계속하기`를 제공한다.
-- 식: JS의 연산자, 배열, 객체를 사용한다. 참·거짓·비어있음은 기존 변환을 따른다.
-  Python의 `and`, `or`, `in`, 리스트 컴프리헨션, 음수 인덱스는 제공하지 않는다.
+| 기능 | 문장 |
+| --- | --- |
+| 변수 | `이름은 값이다`, 재대입은 `이름 = 값` |
+| 타입 있는 변수 | `점수: 숫자는 90이다` |
+| 고정값 | `기준은 80으로 고정한다` |
+| 함수 | `더함(가: 숫자, 나: 숫자)를 정의한다:` |
+| 반환 | `돌려주기 값`, 값 없이도 가능 |
+| 조건 | `만약 식 이라면:` / `아니고 식 이라면:` / `아니면:` |
+| 반복 | `각 항목을 목록에서:` / `동안 식:` |
+| 반복 제어 | `멈추기` / `계속하기` |
+
+은·는과 을·를은 둘 다 허용합니다. 타입 없는 인자는 `any`, 빈 목록 선언은 `any[]`가 됩니다.
+타입은 `숫자`, `문자열`, `논리`(또는 `불리언`), `모름`, `아무거나`, `무효`를 사용하거나 TypeScript 타입 표현식을 작성할 수 있습니다.
+표현식은 JavaScript 연산자·배열·객체·정규식·템플릿 문자열을 사용합니다.
+`참`, `거짓`, `비어있음`, `정의안됨`은 리터럴입니다. 문자열·주석·속성 이름은 치환하지 않습니다.
+JS 전역 `Math`, `JSON`, `Map`, `Set`, `Date`, `Error` 등은 원래 이름으로 사용합니다.
+임의의 JS/TS 선언·중괄호 블록을 소스로 작성하는 문법은 지원하지 않습니다.
+
+## 선택과 한 번 이상 반복
+
+```text
+상태는 "완료"이다
+상태에 따라:
+    "준비"인 경우:
+        출력("준비 중")
+    "완료"인 경우:
+        출력("끝")
+    그 밖의 경우:
+        출력("알 수 없음")
+
+횟수는 0이다
+먼저 실행한다:
+    횟수 = 횟수 + 1
+횟수 < 3인 동안 반복한다
+```
+
+선택 분기는 다음 분기로 넘어가지 않습니다. `그 밖의 경우:`는 기본 분기입니다.
+
+## 모듈
+
+```text
+"./math.js"에서 { 더함 }을 가져온다
+"./settings.js"에서 설정을 가져온다
+
+계산(값: 숫자)를 정의한다:
+    돌려주기 더함(값, 설정.기준)
+
+계산을 공개한다
+```
+
+여러 이름은 `{ 계산, 더함 }을 공개한다`, 기본 내보내기는 `계산을 기본으로 공개한다`로 작성합니다.
+가져오기·공개 문장은 최상위에서만 사용합니다. CLI는 `.hgs` 모듈 그래프를 묶거나 경로를 바꾸지 않으므로 미리 빌드한 `.js` 경로를 사용합니다.
+React·Vue의 Vite 플러그인은 `.hgs` import를 빌드할 때 처리합니다.
+
+## 비동기·생성기·오류 처리
+
+```text
+비동기로 계산(값: 숫자)를 정의한다:
+    결과는 기다리기 Promise.resolve(값 * 2)이다
+    돌려주기 결과
 
-## 기본 함수
+차례로 목록()를 정의한다:
+    내주기 1
+    내주기 2
+
+시도한다:
+    오류를 일으킨다 새 Error("입력을 확인하세요")
+오류를 잡으면:
+    출력(String(오류))
+마지막으로:
+    출력("마침")
+```
+
+`기다리기`는 비동기 함수의 식 맨 앞에 사용합니다. `내주기`는 `차례로` 정의한 함수 안에서 사용합니다.
+브라우저 데모는 네트워크·외부 모듈을 제공하지 않습니다. 모듈과 외부 API 연동은 로컬 프로젝트에서 사용하세요.
+
+## 클래스·자료형·제네릭
+
+```text
+사람 클래스를 정의한다:
+    이름: 문자열은 ""이다
+    생성할 때(이름: 문자열):
+        자신.이름 = 이름
+    소개()를 정의한다:
+        돌려주기 자신.이름
+    별명을 읽으면:
+        돌려주기 자신.이름
+    별명을 바꾸면(값: 문자열):
+        자신.이름 = 값
+
+사람을 이어받아 학생 클래스를 정의한다:
+    생성할 때(이름: 문자열):
+        부모(이름)
+
+사용자는 새 학생("하늘")이다
+출력(사용자.소개())
+
+상자<T> 자료형을 정의한다:
+    값: T
+숫자상자 타입은 상자<숫자>이다
+상태 열거값을 정의한다:
+    준비
+    완료
+복사<T>(값: T)를 정의한다:
+    돌려주기 값
+```
+
+자료형·타입 별칭·열거값은 최상위에 작성합니다. 클래스의 추상·접근 제한자·데코레이터 및 전체 TypeScript 문법은 지원 범위가 아닙니다.
+
+## 기본 함수 15개
 
 | 함수 | 의미 |
 | --- | --- |
 | `출력(...값)` | 콘솔 출력 |
-| `길이(문자열 또는 목록)` | UTF-16 코드 단위 또는 항목 수 |
-| `합계(숫자목록)` | 합산 |
-| `정렬(숫자목록)` | 원본을 바꾸지 않고 오름차순 정렬 |
-| `범위(끝)` / `범위(시작, 끝, 간격)` | 끝 제외, 음수 간격 지원, 최대 10만 항목 |
+| `길이(값)` | 문자열 UTF-16 코드 단위 또는 목록 항목 수 |
 | `추가(목록, 값)` | 원본 목록에 추가 |
 | `포함(목록, 값)` | 포함 여부 |
-| `나누기(문자열, 구분자)` | 문자열 분리 |
-| `잇기(목록, 구분자)` | 기본 구분자 빈 문자열로 연결 |
-
-위 이름은 문장형 파일에 생성하는 기본 함수이므로 사용자 함수·변수 이름으로 쓰지 않는다.
-생성한 TypeScript에는 기본 함수의 구현이 포함된다. 독립 모듈로 사용하려면
-TypeScript 프로젝트의 moduleDetection 설정 또는 export로 모듈 범위를 지정한다.
-
-## 다음 개선 우선순위
-
-1. **독립 토큰화와 AST**: 현재 행 기반 문장 파서·키워드 치환기를 통합한다.
-   정규식 리터럴, 여러 줄 식, 복잡한 클래스/제네릭 문법은 완전 지원 범위가 아니다.
-2. **원본 위치 진단과 소스맵**: 들여쓰기 오류는 .hgs 행 번호를 표시하지만
-   TypeScript 타입 진단은 현재 확장된 생성 코드 위치를 사용한다.
-3. **표준 라이브러리 계약**: 문자열/목록/사전/날짜를 같은 함수 체계로 확장하고
-   Unicode 문자 수·동등성·정렬·오류 모델을 명시한다.
-4. **VS Code/LSP**: 강조, 자동 완성, 한글 오류 설명, 포맷터를 추가한다.
-5. **웹 프로젝트 통합**: Vite 플러그인과 .hgs 모듈 그래프를 구현한다.
-   현재 CLI는 파일 단위 변환이며 .hgs import 경로를 재작성하지 않는다.
-
-문장형은 실험판이다. 웹 데모는 문법 변환·JS 구문 진단만 하며 전체 타입 검사는 하지 않는다.
-DOM과 네트워크가 필요한 결과물은 신뢰하는 로컬 프로젝트에서 생성 TS를 통합해 만든다.
+| `나누기(글, 구분자)` / `잇기(목록, 구분자)` | 문자열 분리·연결 |
+| `다듬기(글)` | 양 끝 공백 제거 |
+| `숫자로(값)` | 빈 문자열·비유한 숫자는 오류 |
+| `합계(목록)` / `평균(목록)` | 합계·평균, 빈 평균은 오류 |
+| `최솟값(목록)` / `최댓값(목록)` | 빈 목록은 오류 |
+| `반올림(값, 자리=0)` | JS Math.round, 자리 -10~10 |
+| `정렬(목록)` | 원본을 복사해 숫자 오름차순 정렬 |
+| `범위(끝)` / `범위(시작, 끝, 간격)` | 끝 제외, 음수 간격 지원, 최대 10만 항목 |
 
-## 0.3 실행·출력과 추가 함수
+기본 함수 이름은 사용자 선언 이름으로 사용하지 않습니다. JS 부동소수점·반올림 규칙을 따르며 Python 호환·임의 정밀도 십진 연산을 의미하지 않습니다.
 
-CLI의 기본 빌드는 `.js` + `.d.ts`이며 `--typescript`로 기존 TS 출력을 선택한다.
-`ksc run 파일.hgs`는 생성 파일 없이 타입 검사 후 Node.js에서 실행한다.
-JS 출력은 ESM이며, 프로젝트는 `type: module` 또는 ESM 번들러를 사용한다.
-공개 함수에 `내보내기 { 함수이름 }`을 쓰면 해당 타입을 .d.ts로 배포할 수 있다.
+## 화면 함수 5개
 
-추가 기본 함수: `숫자로(값)`, `다듬기(문자열)`, `반올림(값, 자리=0)`,
-`평균(목록)`, `최솟값(목록)`, `최댓값(목록)`.
-평균/최솟값/최댓값의 빈 목록과 숫자로의 빈 문자열·비유한 숫자는 오류다.
-반올림은 JS Math.round 규칙이며 십진 임의 정밀도나 Python round와 같은 규칙을 보장하지 않는다.
+`숫자입력("이름", 0)`, `글자입력("이름", "")`, `선택입력("이름", ["하나", "둘"], "하나")`로 입력값을 읽습니다.
+`"계산하기" 버튼을 누르면:` 뒤의 블록은 해당 버튼을 눌렀을 때 실행합니다.
+`버튼("이름")`도 같은 조건을 반환하며 `보여주기("이름", 값)`은 결과 카드를 만듭니다.
+버튼을 누를 때마다 현재 입력값으로 전체 프로그램을 다시 실행합니다. 일반 변수는 실행 사이에 유지되지 않습니다.
+이름은 중복할 수 없으며 한 실행당 최대 40개 화면 요소를 제공합니다.
+화면 함수는 데모 UI 실행 환경이 필요하며 Node CLI 단독 실행이나 React·Vue 컴포넌트 자동 생성 기능은 아닙니다.
 
-## 이름과 확장자 이전 (0.4)
+## 실행·진단 범위
 
-제품명은 한글스크립트(HangulScript), 패키지는 `@uiwwsw/hangulscript`입니다.
-기본 소스 확장자는 `.hgs`이며 기존 `.ks` 파일도 CLI에서 계속 지원합니다.
-이전 패키지에서 이동하려면 `npm uninstall @uiwwsw/koreanscript` 후 새 패키지를 설치하세요.
+`ksc build`는 타입 검사 후 JS와 .d.ts를 생성합니다. `ksc run`은 신뢰하는 로컬 코드를 Node.js에서 실행합니다.
+`--typescript`는 중간 TypeScript 확인용 출력입니다. 별도의 소스 문법 모드가 아닙니다.
+웹 데모와 Vite 플러그인은 문법 변환·JS 구문 진단을 제공하며 전체 타입 검사는 하지 않습니다.
+문장 오류는 원본 행 번호를 표시합니다. TypeScript 타입 진단은 생성 코드 위치를 사용하며 원본 소스맵은 아직 제공하지 않습니다.
+임의의 한국어를 해석하는 AI 실행기·Python 호환 언어·전체 JavaScript/TypeScript 대체 언어가 아닙니다.

package/README.md

@@ -1,14 +1,16 @@
 # 한글스크립트 · HangulScript
 
+[![CI on main](https://github.com/uiwwsw/hangulscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/uiwwsw/hangulscript/actions/workflows/ci.yml)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/uiwwsw/hangulscript/blob/main/LICENSE)
+
 **한글 문장으로 작성하고, JavaScript와 타입 선언으로 배포하는 실험적 프로그래밍 언어.**
 
 Python의 들여쓰기와 익숙한 기본 함수, JavaScript의 표현식과 웹 생태계,
 TypeScript의 타입 검사를 결합합니다. 소스 확장자는 **`.hgs`**입니다.
 
-[온라인에서 실행하기](https://hangulscript.vercel.app/) · [문법 명세](LANGUAGE.md) · [릴리스](https://github.com/uiwwsw/hangulscript/releases) · [의견 보내기](https://github.com/uiwwsw/hangulscript/issues)
+[온라인에서 실행하기](https://hangulscript.vercel.app/) · [React·Vue 사용법](docs/frameworks.md) · [문법 명세](LANGUAGE.md) · [릴리스](https://github.com/uiwwsw/hangulscript/releases) · [의견 보내기](https://github.com/uiwwsw/hangulscript/issues)
 
-```ks
-문장으로 시작
+```text
 점수들은 [75, 92, 88]이다
 각 점수를 점수들에서:
     만약 점수 >= 80 이라면:
@@ -30,9 +32,9 @@ Python 소스 호환이나 전체 TypeScript 문법 지원을 뜻하지 않습
 | [성적 분석기](examples/scores.hgs) | 점수 목록 | 반복·필터링·정렬 |
 | [타입 있는 함수 모듈](examples/math-library.hgs) | 함수·타입 | JS + .d.ts 라이브러리 빌드 |
 
-데모에서 예제를 선택하고 입력값을 바꾼 다음 **실행하기**를 누르세요.
-입력값 변경은 예제 코드를 다시 생성하며, 코드를 직접 편집하면 입력란은 숨겨집니다.
-독립적인 웹 UI·데이터베이스·외부 API를 언어 자체에서 제공하는 단계는 아닙니다.
+데모에서 예제를 선택하고 입력값을 바꾼 다음 **실행하기**를 누르세요. 변환 결과는 기본적으로 JavaScript로 표시하며, 선택 메뉴에서 TypeScript와 비교할 수 있습니다. 실행 결과 패널은 데모를 스크롤하는 동안 화면 하단에 붙어 있습니다. CLI 빌드는 JavaScript와 `.d.ts`를 함께 생성합니다.
+화면 예제에서는 입력값을 바꾸고 도구 안의 버튼을 누르면 현재 값으로 프로그램을 다시 실행합니다.
+데모는 입력창·선택창·버튼·결과 카드를 제공합니다. 데이터베이스·외부 API는 제공하지 않습니다.
 생성한 JS를 기존 웹/Node 프로젝트에 연결해 화면과 서비스를 확장할 수 있습니다.
 
 ## 설치
@@ -76,7 +78,7 @@ npx ksc --typescript examples/math-library.hgs --out-dir output
 ```
 
 **0.2에서 변경:** CLI의 기본 출력이 `.ts`에서 **`.js` + `.d.ts`**로 바뀝니다.
-기존 자동화가 `.ts`를 기대한다면 `--typescript`를 추가하세요.
+중간 TypeScript를 확인하려면 `--typescript`를 추가하세요. 소스는 문장형 하나만 지원합니다.
 `compileSource`·`compileString` API는 기존처럼 TypeScript 문자열을 반환합니다.
 
 `run`은 신뢰하는 코드를 로컬 Node.js에서 실행합니다. 온라인 데모와 달리 격리·2초 제한이 없습니다.
@@ -84,11 +86,10 @@ npx ksc --typescript examples/math-library.hgs --out-dir output
 
 ### 배포 산출물 사용
 
-```ks
-문장으로 시작
+```text
 더함(가: 숫자, 나: 숫자)를 정의한다:
     돌려주기 가 + 나
-내보내기 { 더함 }
+더함을 공개한다
 ```
 
 생성한 `.js`에는 실행 코드가, `.d.ts`에는 다음과 같은 타입 계약이 담깁니다.
@@ -111,8 +112,9 @@ ESM을 지원하는 번들러를 사용하세요. JS와 .d.ts를 함께 배포
 
 ## 문장형 문법
 
-```ks
-문장으로 시작
+문장형이 유일한 기본 문법입니다. 별도의 시작 문장 없이 첫 줄부터 작성합니다.
+
+```text
 이름은 "하늘"이다
 횟수는 3이다
 
@@ -133,16 +135,6 @@ ESM을 지원하는 번들러를 사용하세요. JS와 .d.ts를 함께 배포
 - 블록은 콜론 뒤에 공백으로 들여씁니다. 탭은 허용하지 않습니다.
 - 행 전체 주석은 `#`입니다. 표현식은 JS의 연산자·배열·객체를 사용합니다.
 
-기존 키워드형도 사용할 수 있습니다.
-
-```ks
-상수 이름 = "철수";
-함수 인사(사람: 문자열): 문자열 {
-  반환 "안녕, " + 사람;
-}
-콘솔.출력(인사(이름));
-```
-
 지원 범위와 제약은 [LANGUAGE.md](LANGUAGE.md)에 정리했습니다.
 
 ## 한글 기본 함수
@@ -186,17 +178,11 @@ ESM을 지원하는 번들러를 사용하세요. JS와 .d.ts를 함께 배포
 
 - **컴파일 전용 Worker:** TypeScript 파싱·변환·출력 정리를 UI 스레드 밖에서 실행.
 - **180ms 입력 지연과 결과 재사용:** 키를 누를 때마다 변환하지 않고, 같은 소스는 다시 컴파일하지 않음.
-- **키워드 첫 글자별 탐색:** 모든 문자에서 전체 키워드 목록을 순회하지 않음.
-- **불필요한 재처리 생략:** 기본 함수 코드를 다시 치환하지 않고, 클래스가 없으면 클래스 보정도 생략.
+- **단일 문장형 파서:** 모드 자동 감지·키워드 치환·클래스 사후 보정을 제거하고 문장 블록을 직접 생성.
 - **실행 출력 제한:** 부모 페이지에서도 최대 100행·행당 1,000자로 제한.
 - **범위 제한:** `범위`는 최대 100,000개 항목. 최솟값·최댓값은 인자 펼치기 없이 순회.
 
-2026-10-22 Node 24.18.0 환경에서 같은 1,000행 선언 코드를 측정했을 때,
-변환 중앙값은 변경 전 약 **4.45ms**, 변경 후 약 **0.65ms**였습니다.
-개선 후 20회 측정 p95는 약 **1.88ms**였고, 작은 코드의 타입 검사·JS/.d.ts 생성은 약 **168ms**였습니다.
-서로 다른 기기·입력·브라우저에서 같은 수치를 보장하는 벤치마크는 아닙니다.
-
-화면 JS는 약 **10.4KB**, 컴파일러 Worker는 약 **3.58MB**입니다(압축 전).
+성능은 `npm run benchmark`로 1,000행 문장형 선언의 변환 시간과 현재 번들 크기를 측정할 수 있습니다.
 Worker 분리는 UI의 파싱·실행 부담을 분리하지만 전체 다운로드를 제거하지 않습니다.
 첫 로딩은 네트워크와 기기에 따라 느릴 수 있습니다.
 
@@ -215,7 +201,7 @@ npm run benchmark
 ```js
 import { buildSource, lintSource } from '@uiwwsw/hangulscript';
 
-const source = '문장으로 시작\n출력(합계([1, 2, 3]))';
+const source = '출력(합계([1, 2, 3]))';
 const { javascript, declaration } = buildSource(source);
 const { hasErrors } = lintSource(source);
 ```
@@ -224,7 +210,7 @@ Node 파일 API 없이 변환만 필요하면:
 
 ```js
 import { compileSource } from '@uiwwsw/hangulscript/browser';
-const typescript = compileSource('문장으로 시작\n출력("안녕")');
+const typescript = compileSource('출력("안녕")');
 ```
 
 이 진입점도 TypeScript 스캐너를 포함합니다. 브라우저에서는 데모처럼 Worker에서 사용하세요.
@@ -243,7 +229,7 @@ npm pack --dry-run
 Vercel은 GitHub main과 연결되어 `site-dist/`를 배포합니다.
 `SITE_URL`에 HTTPS origin을 지정하면 canonical·Open Graph·robots·sitemap 주소를 바꿀 수 있습니다.
 
-향후에는 독립 AST·원본 `.hgs` 소스맵·LSP·모듈 그래프·Vite 연동 순으로 확장할 계획입니다.
+Vite 연동을 제공합니다. 독립 AST·원본 `.hgs` 소스맵·LSP·모듈 그래프는 향후 과제입니다.
 
 ## 라이선스
 
@@ -252,5 +238,70 @@ Vercel은 GitHub main과 연결되어 `site-dist/`를 배포합니다.
 ## 이름과 확장자 이전 (0.4)
 
 제품명은 한글스크립트(HangulScript), 패키지는 `@uiwwsw/hangulscript`입니다.
-기본 소스 확장자는 `.hgs`이며 기존 `.ks` 파일도 CLI에서 계속 지원합니다.
+0.6부터 소스 확장자는 `.hgs`만 지원하며 키워드형과 시작 표기를 제거했습니다. 기존 코드는 [문법 명세](LANGUAGE.md)의 문장형으로 옮겨야 합니다.
 이전 패키지에서 이동하려면 `npm uninstall @uiwwsw/koreanscript` 후 새 패키지를 설치하세요.
+
+
+## 입력창과 버튼으로 도구 만들기
+
+온라인 데모의 계산기·할인·통계·문자열 예제는 코드에 선언한 실제 화면을 제공합니다.
+
+```text
+가격은 숫자입력("상품 가격", 10000)이다
+할인율은 숫자입력("할인율", 20)이다
+
+"계산하기" 버튼을 누르면:
+    결과는 가격 * (1 - 할인율 / 100)이다
+    보여주기("결제 금액", 결과)
+```
+
+`숫자입력`, `글자입력`, `선택입력`, `버튼`, `보여주기`를 지원합니다.
+버튼을 누르면 현재 입력값과 누른 버튼 이름을 전달하여 프로그램을 처음부터 다시 실행합니다.
+일반 변수는 실행 사이에 유지되지 않으며 입력값은 같은 화면을 사용하는 동안 유지됩니다.
+화면 요소 이름은 중복할 수 없고, 한 실행당 최대 40개입니다.
+공유받은 코드는 실행 버튼을 눌러야 시작합니다. 공유 링크에는 코드와 코드의 기본값이 담기며, 미리보기에서 바꾼 입력값은 포함하지 않습니다.
+
+이 화면 함수는 데모의 UI 실행 환경이 필요합니다. Node CLI에서 직접 실행하거나 React/Vue 컴포넌트 안에 넣는 것으로 화면이 생성되지는 않습니다.
+사용자 코드는 격리된 Worker에서 실행하고, 호스트는 제한된 데이터만 받아 입력창과 결과 카드를 만듭니다.
+HTML·이벤트 핸들러 문자열을 삽입하지 않습니다.
+
+## React·Vue에서 .hgs 가져오기
+
+**0.6.0 이상**의 공통 Vite 플러그인을 사용합니다. React/Vue의 화면과 상태 관리에 한글스크립트 계산·검증 함수를 연결할 수 있습니다.
+
+```bash
+npm install --save-dev @uiwwsw/hangulscript@^0.6.0
+```
+
+```js
+// vite.config.js — React
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import hangulscript from '@uiwwsw/hangulscript/vite';
+
+export default defineConfig({ plugins: [hangulscript(), react()] });
+```
+
+Vue에서는 `@vitejs/plugin-vue`에서 `vue`를 가져와 `[hangulscript(), vue()]`로 설정합니다.
+
+```text
+결제금액(가격: number, 할인율: number)를 정의한다:
+    돌려주기 가격 - 반올림(가격 * 할인율 / 100)
+결제금액을 공개한다
+```
+
+```js
+import { 결제금액 } from './discount.hgs';
+console.log(결제금액(10000, 20)); // 8000
+```
+
+완성된 **입력창 → 버튼 → 계산 결과** 예제와 React JSX·Vue SFC 전체 코드를 제공합니다.
+
+- [React·Vue 단계별 사용 안내](docs/frameworks.md): 설치·설정·한글 함수·컴포넌트 연결·TypeScript 사용법
+- [실행 가능한 React 예제](examples/react-vite): 해당 폴더에서 `npm ci` → `npm run dev`
+- [실행 가능한 Vue 예제](examples/vue-vite): 해당 폴더에서 `npm ci` → `npm run dev`
+- [온라인 연동 안내](https://hangulscript.vercel.app/#frameworks)
+
+예제는 Node.js `^20.19.0 || >=22.12.0`이 필요하며 Node.js 24에서 검증했습니다.
+Vite 플러그인은 타입 검사·선언 생성·소스맵을 제공하지 않습니다. TypeScript 프로젝트는 `ksc build`로 생성한 `.js`와 `.d.ts`를 가져오는 방식이 적합합니다.
+데모의 UI 문장을 React/Vue 컴포넌트로 자동 변환하는 기능은 포함하지 않습니다.

package/dist/cli.js

@@ -12,7 +12,7 @@ function usage() {
 옵션:
   -o, --out-dir <경로>   출력 디렉터리 (기본: 입력 파일 옆)
   --check                타입 검사만 실행
-  --typescript           기존 .ts 출력 모드
+  --typescript           변환된 TypeScript 확인용 출력
   -h, --help             도움말
 
 문장형은 실험판입니다. run은 신뢰하는 로컬 코드만 실행하세요.`);
@@ -34,7 +34,7 @@ async function main() {
     } else if (arg === '--check') check = true;
     else if (arg === '--typescript') typescript = true;
     else if (arg.startsWith('-')) throw new Error(`알 수 없는 옵션: ${arg}`);
-    else if (!(/\.(?:hgs|ks)$/.test(arg))) throw new Error('입력 파일은 .hgs 확장자여야 합니다.');
+    else if (!(/\.hgs$/.test(arg))) throw new Error('입력 파일은 .hgs 확장자여야 합니다.');
     else inputs.push(arg);
   }
   if (!inputs.length) throw new Error('입력 .hgs 파일을 지정하세요.');

package/dist/expressions.js

@@ -0,0 +1,59 @@
+import ts from 'typescript';
+
+const literals = new Map([['참', 'true'], ['거짓', 'false'], ['비어있음', 'null'], ['정의안됨', 'undefined'], ['자신', 'this'], ['부모', 'super']]);
+const types = new Map([['숫자', 'number'], ['문자열', 'string'], ['논리', 'boolean'], ['불리언', 'boolean'], ['아무거나', 'any'], ['모름', 'unknown'], ['무효', 'void']]);
+
+function identifiers(source, replacements) {
+  const file = ts.createSourceFile('expression.ts', source, ts.ScriptTarget.Latest, true);
+  const edits = [];
+  const visit = node => {
+    if (ts.isIdentifier(node) && replacements.has(node.text)) {
+      const p = node.parent;
+      const property = (ts.isPropertyAccessExpression(p) && p.name === node) ||
+        ((ts.isPropertyAssignment(p) || ts.isMethodDeclaration(p) || ts.isPropertySignature(p)) && p.name === node);
+      if (!property) edits.push([node.getStart(file), node.end, replacements.get(node.text)]);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  for (const [start, end, value] of edits.reverse()) source = source.slice(0, start) + value + source.slice(end);
+  return source;
+}
+
+export function expression(source) {
+  source = source.replace(/^새\s+/, 'new ').replace(/^기다리기\s+/, 'await ');
+  if (/[참거비정자부]/.test(source)) {
+    const prefix = 'const __expression = (';
+    source = identifiers(prefix + source + ');', literals).slice(prefix.length, -2);
+  }
+  return source;
+}
+
+export function typeExpression(source) {
+  const prefix = 'type __Type = ';
+  return identifiers(prefix + source, types).slice(prefix.length);
+}
+
+export function signature(source, name = '__fn') {
+  const file = ts.createSourceFile('signature.ts', `function ${name}${source} {}`, ts.ScriptTarget.Latest, true);
+  const fn = file.statements[0];
+  if (file.parseDiagnostics.length || !ts.isFunctionDeclaration(fn)) throw new SyntaxError('함수 이름·매개변수·타입을 확인하세요.');
+  return fn.parameters.map(param => {
+    let printed = param.getText(file);
+    const start = param.getStart(file);
+    const edits = [];
+    if (param.type) edits.push([param.type.getStart(file) - start, param.type.end - start, typeExpression(param.type.getText(file))]);
+    if (param.initializer) edits.push([param.initializer.getStart(file) - start, param.initializer.end - start, expression(param.initializer.getText(file))]);
+    for (const [from, to, value] of edits.sort((a, b) => b[0] - a[0])) printed = printed.slice(0, from) + value + printed.slice(to);
+    if (!param.type && !param.initializer) printed += param.dotDotDotToken ? ': any[]' : ': any';
+    return printed;
+  }).join(', ');
+}
+
+export function statement(source) {
+  const file = ts.createSourceFile('statement.ts', source, ts.ScriptTarget.Latest, true);
+  if (file.parseDiagnostics.length || file.statements.length !== 1 || !ts.isExpressionStatement(file.statements[0])) {
+    throw new SyntaxError('문장형 구문을 사용하세요. 선언은 「이름은 값이다」, 함수는 「이름(...)를 정의한다:」로 작성합니다.');
+  }
+  return source.replace(/;$/, '') + ';';
+}

package/dist/index.js

@@ -141,7 +141,7 @@ export { compileSource };
 /** Compile through TypeScript once, emitting executable JS and declarations in memory. */
 export function buildSource(source, filePath = 'input.hgs') {
   const ts = loadTypeScriptModule();
-  const virtualPath = path.resolve(filePath).replace(/\.(?:hgs|ks)$/i, '') + '.ts';
+  const virtualPath = path.resolve(filePath).replace(/\.hgs$/i, '') + '.ts';
   const compiled = compileSource(source);
   const options = {
     target: ts.ScriptTarget.ES2022,

package/dist/runtime.js

@@ -0,0 +1,45 @@
+import { uiRuntime } from './ui.js';
+export const sentenceRuntime = `${uiRuntime}
+
+function 출력(...값: unknown[]): void { console.log(...값); }
+function 길이(값: string | readonly unknown[]): number { return 값.length; }
+function 추가<T>(목록: T[], 값: T): void { 목록.push(값); }
+function 포함<T>(목록: readonly T[], 값: T): boolean { return 목록.includes(값); }
+function 나누기(글: string, 구분: string): string[] { return 글.split(구분); }
+function 잇기(목록: readonly unknown[], 구분 = ""): string { return 목록.join(구분); }
+function 합계(값: readonly number[]): number { return 값.reduce((합, 항목) => 합 + 항목, 0); }
+function 숫자로(값: string | number): number {
+  if (typeof 값 === "string" && 값.trim() === "") throw new Error("빈 문자열은 숫자로 바꿀 수 없습니다.");
+  const 결과 = Number(값);
+  if (!Number.isFinite(결과)) throw new Error("유한한 숫자를 입력하세요.");
+  return 결과;
+}
+function 다듬기(글: string): string { return 글.trim(); }
+function 반올림(값: number, 자리 = 0): number {
+  if (!Number.isFinite(값) || !Number.isInteger(자리) || 자리 < -10 || 자리 > 10) throw new Error("유한한 수와 -10~10 사이의 정수 자리가 필요합니다.");
+  return Math.round(값 * 10 ** 자리) / 10 ** 자리;
+}
+function 평균(목록: readonly number[]): number {
+  if (!목록.length) throw new Error("빈 목록의 평균을 구할 수 없습니다.");
+  return 합계(목록) / 목록.length;
+}
+function 최솟값(목록: readonly number[]): number {
+  if (!목록.length) throw new Error("빈 목록의 최솟값을 구할 수 없습니다.");
+  let 결과 = 목록[0]; for (const 항목 of 목록) if (항목 < 결과) 결과 = 항목;
+  return 결과;
+}
+function 최댓값(목록: readonly number[]): number {
+  if (!목록.length) throw new Error("빈 목록의 최댓값을 구할 수 없습니다.");
+  let 결과 = 목록[0]; for (const 항목 of 목록) if (항목 > 결과) 결과 = 항목;
+  return 결과;
+}
+function 정렬(값: readonly number[]): number[] { return [...값].sort((가, 나) => 가 - 나); }
+function 범위(시작: number, 끝?: number, 간격 = 1): number[] {
+  if (끝 === undefined) { 끝 = 시작; 시작 = 0; }
+  if (!Number.isFinite(시작) || !Number.isFinite(끝) || !Number.isFinite(간격) || 간격 === 0) throw new Error("범위에는 유한한 수와 0이 아닌 간격이 필요합니다.");
+  const 개수 = Math.max(0, Math.ceil((끝 - 시작) / 간격));
+  if (개수 > 100000) throw new Error("범위는 최대 100000개까지 만들 수 있습니다.");
+  return Array.from({ length: 개수 }, (_, 순서) => 시작 + 순서 * 간격);
+}
+`;
+