path: root/prototypes/workbench/README.md

# 빈 작업물에서 시작하는 Pure

자신이 만들고 싶은 작은 동작을 작성하는 실험이다. 처음에는 코드·장면·입력이
모두 비어 있다. 상태, 입력, 도형과 동작을 추가하는 데 실행기 소스를 고칠 필요가 없다.

이 디렉터리는 브라우저·CLI 검증 호스트, 선택 가능한 네이티브 계산 모듈과 Linux GTK 작성 창이다.
Pure의 최종 목표는 앱 로직·네트워크·RPC·DB·UI를 다루는 독립 네이티브 애플리케이션 런타임이다.
UI는 그중 하나의 하위 체계이며, 현재 호스트는 전체 런타임이나 일반 네이티브 UI 스택이 아니다.
네이티브 코어 검사와 Wasm 크기도 네이티브 UI 완성이나 전체 메모리 효율의 근거가 아니다.
현재 개발 방향은 [로드맵](../../docs/research/010-roadmap.md)을 따른다.

CLI에는 기존 작업물을 실제 네이티브 서버·바이트 저장소에 저장하고 새 실행기에서 복원하는
`connect`·`push`·`pull`이 추가됐다. [서버 실행과 사용법](../connections/README.md)을 따른다.
브라우저 저장 버튼은 이 서버에 자동 연결되지 않는다.

같은 `.pure`를 **Node·브라우저 없이 실행하는 네이티브 프로그램**으로 빌드하는 경로도 있다.
빌드 시 기존 컴파일러를 재사용하며, 입력·상태 스냅샷·저장·복원을 C 실행 코어에 연결했다.
실행 전용 터미널 프로그램, 선택형 GTK 작성 창, 선택형 TLS 피어 호스트가 있다.
[빌드와 사용법](native/README.md), [작성 창의 비용과 검증](../../docs/research/025-native-authoring-shell.md),
[피어 연결과 전체 비용](../../docs/research/026-secure-peer-link.md).

## 열기

저장소 루트에서 다음 명령을 실행한다. Python 3가 필요하며, 포함된 Wasm으로 바로 열린다.

```sh
python3 prototypes/workbench/manage.py serve --port 8766
```

[제작 화면](http://127.0.0.1:8766)을 연다. 기존 Dino 실험은 8765 포트를 사용한다.
서버는 로컬 컴퓨터에서만 접속할 수 있다.

## 직접 만드는 흐름

1. 먼저 만들고 싶은 작은 동작을 정한다. 무엇을 기억하고, 어떤 입력에 어떻게 바뀔지 정하면 된다.
2. 빈 편집기에 작성한다. 화면 아래 **언어 안내**의 조각을 조합해도 된다.
3. **코드 적용**을 누르면 도형과 선언한 입력 버튼이 생긴다.
4. 버튼을 눌러보거나 장면을 클릭한 뒤 지정한 키를 누른다. `on frame`이 있다면 **실행** 또는 **한 프레임**으로 시간을 진행한다.
5. 필요한 상태·입력·도형·반응을 더 작성하고 다시 적용한다. 같은 이름의 상태 값은 이어진다.
6. **.pure 저장**으로 코드를, **배치 저장**으로 코드와 현재 배치를 보관한다. 새로고침으로 복원되지 않으므로 저장이 필요하다.

문법이 막힐 때 볼 수 있는 최소 예시다. 이 예시를 실행하는 것 자체가 제작 경험 평가를 뜻하지는 않는다.

```text
state x = 80
input right = ArrowRight
circle seed(x, 180, 20, "#7ed9ae")
on right.down {
  x = x + 20
}
```

새 반응을 추가할 때 원하는 표현을 찾을 수 있는지, 어디서 막히는지가 이번에 확인할 점이다.
관찰은 **하려던 일 / 실제로 일어난 일 / 기대했던 일** 정도면 된다.
완성된 카운터·충전·전환·직접 조작·세 도형 배치 예제는 별도로 선택해 불러오며 자동 적용하지 않는다.

## 적용·정지·오류의 의미

- 편집 중인 코드와 적용한 코드는 별개다. 저장은 **미적용 변경까지 포함한 편집기 내용**을 저장한다.
- 적용은 같은 이름의 숫자 상태를 보존한다. 새 이름은 초깃값으로 시작하고 삭제한 이름은 사라진다.
  이름 변경을 자동으로 추적하지 않는다. 초깃값만 바꿨다면 **초깃값으로**를 눌러야 현재 값도 바뀐다.
- 문법·이름·용량 오류가 있는 수정은 기존 작업을 유지한 채 거절한다. **문제 위치로**에서 해당 행으로 이동한다.
- 누르는 중에는 적용할 수 없다. 모든 입력을 놓은 뒤 적용한다.
- 정지는 시간 진행만 멈춘다. 입력 버튼은 정지 중에도 작동한다.
- 계산 실패는 해당 이벤트의 모든 상태 변경을 취소한다. 마지막 실패 안내는 놓기 동작으로 사라지지 않으며,
  수정 적용 또는 초기화로 지워진다. 잘못된 도형 크기·표시 계산은 별도의 표시 오류다.
- 편집기나 버튼에 포커스가 있으면 키 입력을 장면에 전달하지 않는다. 장면을 클릭하면 키를 사용할 수 있다.
  창에서 포커스가 벗어나면 시간을 멈추고 누른 입력을 놓는다. 키 입력의 `.up`, 직접 조작 입력의 `.cancel` 동작이 실행될 수 있다.
- 실행은 프레임당 `dt = 1/60`이다. 화면 갱신마다 최대 6프레임을 진행하며, 밀린 나머지는 건너뛰고 횟수를 표시한다.

## 표현할 수 있는 범위

상태는 숫자다. 입력은 키의 누름·놓음과 대상에 연결한 포인터 좌표, 시간은 `on frame`으로 선언한다.
출력은 사각형·원·숫자 글자이며 좌표·크기·표시 값을 상태 표현식에 연결한다.
색상은 `"#rrggbb"` 상수다. 화면 좌표는 640×360 기준이다.

```text
on right.up { x = 80 }
on frame {
  x = x + 30 * dt
  if x > 600 { x = 0 }
}
box tile(x, 220, 40, 40, "#356548")
text label(40, 60, x, "x: ")
```

연산: `+ - * /`, 비교, `&& || !`, `min`, `max`, `clamp`.
논리 연산은 양쪽을 모두 계산한다. `if`의 조건은 한 번만 계산하고 대입은 위에서 아래로 실행한다.
같은 이벤트에 여러 반응을 선언하면 작성 순서대로 실행하며 한 이벤트 전체를 함께 성공·실패 처리한다.
이벤트의 `dt`는 시간 진행에서 1/60, 입력에서는 0이다. 표시 표현식에서는 `dt`를 쓰지 않는다.

키: Space, Enter, 방향키, KeyA~KeyZ, Digit0~Digit9. 한 키는 하나의 입력에 연결한다.
주석은 `#`, 문장 구분은 줄바꿈 또는 세미콜론이다.

한도: 상태 32개, 입력 8개, 도형/글자 24개, 반응 64개, 중간 명령 512개,
계산 스택 64칸, 소스 32,768 UTF-8 바이트. 반복문·일반 함수 호출·문자열 상태·동적 배열은 없다. 매개변수 하나를 받는 공유 반응 규칙은 지원한다.
충돌·중력·점프 등의 동작은 자동으로 제공되지 않는다.
정확한 인터페이스와 명령 형식은 [CONTRACT.md](CONTRACT.md)에 있다.

## 도형을 직접 잡아 조작하기

예제 선택에서 **직접 잡아 이동 → 예제 불러오기 → 코드 적용**을 누른다.
[direct.pure](examples/direct.pure)는 잡은 위치를 유지한 이동, 영역 제한,
연결된 숫자 출력, 취소 시 복귀를 작성한 코드다. 좌우 방향키로도 위치를 바꿀 수 있다.

```text
input drag = pointer(tile)
on drag.move {
  x = clamp(event_x - grab_x, 20, 564)
  y = clamp(event_y - grab_y, 100, 276)
}
```

전체 예제에서 `.down`은 잡은 위치와 시작 위치를 기억하고, `.up`은 마지막으로 표시한 위치를
확정하며, `.cancel`은 시작 위치로 되돌린다. 이 동작은 자동 제공되는 물리가 아니다.
제한 값이나 취소 규칙을 바꾸고 다시 적용하면 동작도 바뀐다.
`event_x/event_y`는 포인터 반응 안에서만 쓸 수 있는 장면 좌표다.
서로 다른 대상은 동시에 조작할 수 있고, 같은 대상의 두 번째 접촉은 무시한다.
초점·캡처를 잃으면 `.cancel`로 끝난다. 하나의 이벤트가 실패하면 그 이벤트만 취소된다.

터미널에서도 같은 정의에 `point drag down 90 170`, `point drag move 360 220`,
`point drag up 410 240`을 보내 재현할 수 있다.
기능 검증과 범위는 [직접 조작 보고서](../../docs/research/013-authored-pointer-input.md)에 기록했다.

## 배치를 저장하고 다시 열기

**세 도형 배치 → 예제 불러오기 → 코드 적용**으로 시작한다.
세 도형을 따로 움직일 수 있고, 마지막으로 잡은 도형은 방향키로 10씩 조정한다.
시간 진행과 조작을 끝낸 뒤 **배치 저장**을 누르면 현재 상태까지 포함된 JSON을 내려받는다.
**파일 열기**로 이 파일을 선택하면 새 페이지에서도 같은 배치가 복원된다.

- 배치 파일에는 적용된 코드, 현재 숫자 상태, 아직 적용하지 않은 편집 초안이 들어 있다.
- 복원은 저장된 코드를 실행 정의로 사용한다. 미완성 초안은 편집기에 남기며 자동 적용하지 않는다.
- 조작 중인 입력과 실행 시계는 복원하지 않는다. 열린 작업은 정지 상태로 시작한다.
- **초깃값으로**는 코드의 원래 초깃값으로 돌아간다. 저장 당시 배치로 돌아가려면 파일을 다시 연다.
- **.pure 저장 / 코드 JSON 저장**은 기존처럼 초안만 저장한다. 배치 저장과 구분한다.
- 잘못된 파일이나 읽는 동안 작업이 바뀐 파일은 기존 작업을 유지한 채 거절한다.

터미널에서도 같은 파일을 쓸 수 있다.

```sh
node prototypes/workbench/cli.mjs my-layout.pure.json
```

명령 `save-project new-layout.json`으로 현재 배치를 저장하고 `restore saved-layout.json`으로
복원한다. 기존 파일을 덮어쓰지 않는다. 브라우저에서 저장한 미적용 초안도 다시 저장할 때 보존한다.

## 같은 규칙을 여러 대상에 연결하기

**공유 규칙으로 배치** 예제는 앞의 세 도형 배치와 같은 작업을 공통 규칙으로 작성한다.
`record`는 필드의 기본값, `item`은 대상별 실제 값, `rule`은 재사용할 반응이다.

```text
record Position { x=0; y=0 }
item green = Position(x=80,y=120)
rule move(t: Position) { t.x=event_x; t.y=event_y }
input drag = pointer(tile)
box tile(green.x,green.y,56,44,"#c9f08b")
on drag.move use move(green)
```

여러 입력을 같은 규칙에 연결해도 규칙의 실행 명령은 한 벌만 저장한다.
매개변수의 필드는 연결된 대상의 값을 직접 바꾼다. 같은 사건의 여러 반응 중 하나가
실패하면 앞의 변경도 함께 취소한다. 대상·필드 선언 순서를 바꾸어 적용해도
`green.x` 같은 이름으로 값을 유지하고, 배치 파일도 그 이름을 저장한다.

규칙은 레코드 매개변수 하나를 받는다. 레코드당 필드는 1~8개이며 모든 대상의 필드는
기존 상태 32개 한도에 포함된다. 실행 중 대상 생성·삭제는 아직 없다.
전체 작성물은 [shared-layout.pure](examples/shared-layout.pure), 결과와 한계는
[공유 규칙 보고서](../../docs/research/015-shared-rules.md)에 있다.

## 여러 도형을 하나의 포인터 입력으로 연결하기

**입력 묶어서 배치 → 예제 불러오기 → 코드 적용**으로 시작한다.

```text
input drag = pointer { green_box: green; blue_box: blue }
on drag.down use grab(drag.target)
on drag.move use move(drag.target)
on drag.up use drop(drag.target)
on drag.cancel use cancel(drag.target)
```

같은 record 타입의 대상을 묶고, 현재 잡은 대상의 필드를 공통 규칙에 전달한다.
도형을 늘려도 이 네 반응을 대상마다 복제하지 않는다. 서로 다른 도형은 동시에
조작할 수 있고 하나를 놓거나 취소해도 다른 도형의 조작은 이어진다.
같은 대상은 한 그룹 연결만 가질 수 있다. 전체 연결 대상은 최대 24개이며
상태 32개 등 기존 한도는 그대로다. 현재 예제의 키보드 선택 연결은 기존 방식이다.

배치 파일은 이전과 같은 방식으로 저장·복원한다. 마지막 입력에는 대상 도형도 표시한다.
CLI에서는 `point-target drag green_box down 90 130`을 사용한다.
[전체 작성물](examples/routed-layout.pure), [구현 결과와 한계](../../docs/research/016-pointer-routing.md).

## 일반 코드와 비교하기

[일반 JavaScript 비교 앱](http://127.0.0.1:8766/baseline.html)은
[충전 예제](examples/charge.pure)와 같은 상태·출력 계산을
[독립 JavaScript 모델](web/baseline.mjs)로 작성한 것이다.
Pure 컴파일러나 실행기를 가져오지 않는다.

JS 모델은 고정된 앱이다. 일반 프로그램의 실행 중 교체나 상태 이전은 제공하지 않는다.
두 파일의 길이만으로 개발 생산성을 비교하지 않는다. 자세한 실행 비용과 범위는
[연구 보고서 004](../../docs/research/004-authoring.md)에 있다.

## 터미널에서 같은 작업 실행하기

Node.js가 필요하다. 검증에 사용한 버전은 24.20.0이다.

```sh
node prototypes/workbench/cli.mjs my-work.pure
```

```text
down right
up right
frame 10
show
load my-work.pure
reset
save saved-work.pure
quit
```

`load`는 같은 이름의 상태를 보존한다. `save`는 적용한 소스를 저장하고 기존 파일은 덮어쓰지 않는다.
경로에 공백이 있으면 명령 뒤에 경로 전체를 입력한다. 별도 따옴표는 붙이지 않는다.
브라우저와 터미널은 동일한 컴파일러·Wasm을 쓰지만 **각자 별도의 실행 상태**를 갖는다.

## 계산 기록과 작업량 제한

표시 계산에 [기록을 버릴 수 있는 실행 계약](../../docs/research/009-bounded-display-integration.md)을
연결했다. 모든 도형에 하나의 작업 한도를 적용한다. 한도를 넘으면 장면 전체를
표시하지 않고 오류를 알린다. 그 전에 성공한 입력 이벤트의 상태는 유지된다.
기본값은 작업량 2,048, 캐시 꺼짐이다. 터미널에서 다음처럼 사용할 수 있다.

```text
limits 32 8 2048
show
costs
forget all
show
limits 32 8 1
limits 32 8 2048
```

`limits`의 숫자는 결과 캐시 개수·변경 기록 개수·표시 작업량이다.
`forget`은 `all`, `values`, `history`를 받는다. `costs`는 마지막 표시 계산의
작업량·명령 수·캐시 적중을 보여준다. 한도가 부족하면 101 표시 오류가 나고,
충분히 늘리면 다시 계산한다. 파이프로 실행한 CLI는 중간 실패도 종료 코드 1에 남긴다.

임베딩 API는 `createRuntime(wasmBytes, {cacheEntries:32, historyEntries:8, workLimit:2048})`,
`configureEvaluation`, `forgetEvaluation`, `evaluationStats`다. 브라우저 작성 화면에는
이 설정을 위한 새 UI를 추가하지 않았다. 저장 공간 반납이나 앱 전체의 메모리·시간
상한을 제공하는 기능은 아니다. 자세한 범위는 [계약](CONTRACT.md)을 따른다.

## 빌드·검증 재현

Zig 0.15.2를 설치하고 저장소 루트에서 실행한다. 다른 경로의 Zig는 `--zig /path/to/zig`로 지정한다.

```sh
python3 prototypes/workbench/manage.py build
node prototypes/workbench/compiler.test.mjs
node prototypes/workbench/runtime.test.mjs
node prototypes/workbench/baseline.test.mjs
node prototypes/workbench/cli.test.mjs
node prototypes/workbench/evaluation.test.mjs
node prototypes/workbench/workspace.test.mjs
node prototypes/workbench/presentation.test.mjs
node prototypes/workbench/routing.test.mjs
node prototypes/workbench/evaluation-check.mjs --output /tmp/pure-evaluation-new.json
node prototypes/workbench/workspace-check.mjs --output /tmp/pure-workspace-new.json
node prototypes/workbench/compare.mjs --output /tmp/pure-comparison-new.json
```

현재 빌드 명령은 네이티브 Zig 검사 37개도 실행한다. 전체 JS 검사는
`node --test prototypes/workbench/*.test.mjs`로 실행하며 현재 87개다.
비교 파일은 덮어쓰지 않으므로 매번 새 출력 경로를 지정한다.
빌드는 `ReleaseSafe`, 디버그 정보 제거, 16 KiB 스택, 초기·최대 선형 메모리 64 KiB다.
산출물과 빌드 기록의 해시로 재현 대상을 확인할 수 있다.

실제 브라우저 조작 시나리오는 [qa-browser.js](qa-browser.js)에 있다.
Playwright CLI 0.1.21의 `run-code`에 함수 전체를 전달하고,
마지막의 `window.__pureWorkbenchQAEvidence`를 후속 읽기로 수집했다.
대화상자·다운로드에서 CLI가 일찍 반환할 수 있으므로 반환 자체를 완료로 간주하지 않는다.
저장된 [브라우저 결과](results/2026-09-22-linux-aarch64/browser-checks.json)는 44개 확인을 포함한다.

이 결과는 Linux aarch64에서 얻었다. M3 macOS, 네이티브 GUI·Metal, 센서 입력,
프로세스 전체 메모리와 실제 사용자의 제작 시간은 아직 측정하지 않았다.

표시 계산의 첫 통합 기록은
[2026-09-22-evaluation](results/2026-09-22-evaluation/verification.json)에 있다.
기존 44개 브라우저 확인은 이전 빌드의 기록이다. 이번 변경의 실제 브라우저
확인 절차는 [qa-evaluation.js](qa-evaluation.js)다.
최신 빌드의 [브라우저 결과](results/2026-09-23-workspace/browser.json)는 12개 확인을 포함한다.
이 절차의 결과는 `window.__pureEvaluationEvidence`에서 읽는다.

현재 빌드는 코드 교체 준비 공간과 계산 기록을 공유한다. 교체 준비 중에도
기존 이벤트와 표시 계산은 실행할 수 있으며, 표시 계산은 기록 없이 재계산한다.
검사·비교 결과는 [2026-09-23-workspace](results/2026-09-23-workspace/verification.json)에 있다.
코어 고정 구조는 19,128 B로, 기록 기능을 넣기 전보다 증가한 전용 공간은
56 B다. 공유 영역을 메모리 합계에 중복해서 더하지 않는다.

현재 화면 갱신은 `present(target)`으로 계산 결과를 기존 DOM 요소에 전달한다.
매 입력마다 전체 장면 스냅샷이나 도형·상태·비용 요소를 다시 만들지 않는다.
CLI·검사용 `snapshot()`은 유지한다. [입력→출력 구현 보고서](../../docs/research/011-direct-presentation.md)에
구조 변경, 추가 공간, 속도 측정의 한계를 기록했다.
직접 출력 통합 당시의 [52개 JS/CLI/Wasm 검사](results/2026-09-23-presentation/verification.json),
[브라우저 경로 비교](results/2026-09-23-presentation/browser.json),
[작성 흐름 검사](results/2026-09-23-presentation/browser-authoring.json),
[표시 한도 검사](results/2026-09-23-presentation/browser-limit.json)를 함께 보존했다.

브라우저 비교는 Playwright CLI 0.1.21로 로컬 페이지를 연 세션에서 다음처럼 재실행한다.
이전 구현은 테스트 전용 응답 교체로 불러오며 현재 제품 파일은 바꾸지 않는다.

```sh
python3 prototypes/workbench/qa-presentation.py --cli /path/to/playwright-cli.js --session pure-presentation --output /tmp/pure-presentation-new.json
```

후속으로 실행 입력과 코드 편집의 갱신 경로를 분리했다. 실행 중인 값이 바뀌어도 소스의
줄 번호·크기·커서 정보를 다시 계산하지 않는다. 실제 소스 변경과 적용 상태는 계속 갱신한다.
[결과 보고서](../../docs/research/012-refresh-ownership.md),
[브라우저 비교](results/2026-09-23-refresh/browser.json),
[작성 흐름](results/2026-09-23-refresh/browser-authoring.json),
[표시 한도](results/2026-09-23-refresh/browser-limit.json)를 보존했다.
이 변경에서 런타임·컴파일러·Wasm은 그대로이며, 이전 단위 검사를 새 검사로 세지 않는다.

```sh
python3 prototypes/workbench/qa-refresh.py --cli /path/to/playwright-cli.js --session pure-path --output /tmp/pure-refresh-new.json
```

## 실제 웹 레이아웃과 문서 편집

[문서 작업 화면](http://127.0.0.1:8766/document.html)은 일반 UTF-8 텍스트를 열고,
수정하고, 옆에서 읽고, `.txt`로 저장하는 작업이다. 기존 작업 화면에도 링크가 있다.

- 넓은 화면에서는 경계를 잡거나 방향키·슬라이더로 두 패널의 비율을 조절한다.
- Esc·접촉 취소는 시작 비율로 돌아간다. 창 크기가 바뀌어도 조작 좌표를 다시 맞춘다.
- 좁은 화면에서는 작성·읽기가 위아래로 놓인다. 각 패널은 브라우저의 스크롤을 사용한다.
- **분할 규칙 수정**에서 `clamp(event_value,20,80)`의 제한을 더 좁혀 적용할 수 있다.
- 파일은 텍스트만 저장한다. 패널 비율과 규칙을 저장하는 별도 문서 형식은 만들지 않았다.

이 화면은 직접 작성한 HTML 호스트다. Pure의 현재 DSL만으로 일반 웹 UI 전체를
작성하게 된 것은 아니다. 레이아웃·텍스트·IME·선택을 VM에 복제하지 않고, 필요한
숫자 조작만 전달한다. 파일은 2 MiB까지, UTF-8을 사용하며 저장 시 줄바꿈은 LF다.
현재 읽기 화면은 문서 편집 시 텍스트 전체를 갱신한다. 전체 앱의 메모리 절감이나
큰 문서 성능 우위는 주장하지 않는다. [결과와 한계](../../docs/research/017-web-layout-boundary.md).

```text
state ratio = 50
input split = value
on split.change { ratio = clamp(event_value,20,80) }
```

웹 호스트 API는 `runtime.change('split',65,'range')`, CLI는 `change split 65`다.
숫자 값은 유한해야 하고 상태 배열에 자동 보관되지 않는다. 필요한 값만 규칙에서 저장한다.