From 5f3094ea442390be50305e258c1501415a6b95c9 Mon Sep 17 00:00:00 2001
From: Jul <kirby88@pm.me>
Date: Tue, 9 Jun 2026 08:54:50 +0100
Subject: [PATCH] =?UTF-8?q?Add=20support=20for=20function=20keys=20(F1?=
 =?UTF-8?q?=E2=80=93F12)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds F1 through F12 as repeatable keypress commands, following the
existing pattern used by keys like PageUp:

- token: new F1–F12 token constants, keyword mappings, and IsCommand
- parser: F1–F12 added to CommandTypes and the keypress switch, so they
  accept the standard `Key[@<time>] [count]` grammar
- command: CommandFuncs entries mapping each F-key to ExecuteKey with the
  corresponding go-rod input.Fn key
- record: F-key terminal escape sequences so `vhs record` captures them
- docs: man page and README "Function Keys" section
- tests: lexer/parser F-key tests; updated command count assertions

Co-authored-by: vix <290354907+vix-agent@users.noreply.github.com>
---
 README.md             | 11 ++++++
 command.go            | 12 ++++++
 command_test.go       |  4 +-
 lexer/lexer_test.go   | 32 ++++++++++++++++
 man.go                |  1 +
 parser/parser.go      | 26 ++++++++++++-
 parser/parser_test.go | 35 ++++++++++++++++++
 record.go             | 86 ++++++++++++++++++++++++-------------------
 token/token.go        | 26 +++++++++++++
 9 files changed, 193 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index 8e3384ae..fe8a4c9a 100644
--- a/README.md
+++ b/README.md
@@ -668,6 +668,17 @@ PageUp 3
 PageDown 5
 ```
 
+#### Function Keys
+
+Press the function keys `F1` through `F12`. Like other keypress commands they
+take an optional `@time` and repeat count: `F3[@<time>] [count]`.
+
+```elixir
+F1
+F3 2
+F5@500ms 3
+```
+
 #### Scroll Up / Down
 
 Scroll the terminal viewport directly with `ScrollUp` and `ScrollDown`.
diff --git a/command.go b/command.go
index 4e5b0d06..e9224b1d 100644
--- a/command.go
+++ b/command.go
@@ -52,6 +52,18 @@ var CommandFuncs = map[parser.CommandType]CommandFunc{
 	token.ESCAPE:      ExecuteKey(input.Escape),
 	token.PAGE_UP:     ExecuteKey(input.PageUp),
 	token.PAGE_DOWN:   ExecuteKey(input.PageDown),
+	token.F1:          ExecuteKey(input.F1),
+	token.F2:          ExecuteKey(input.F2),
+	token.F3:          ExecuteKey(input.F3),
+	token.F4:          ExecuteKey(input.F4),
+	token.F5:          ExecuteKey(input.F5),
+	token.F6:          ExecuteKey(input.F6),
+	token.F7:          ExecuteKey(input.F7),
+	token.F8:          ExecuteKey(input.F8),
+	token.F9:          ExecuteKey(input.F9),
+	token.F10:         ExecuteKey(input.F10),
+	token.F11:         ExecuteKey(input.F11),
+	token.F12:         ExecuteKey(input.F12),
 	token.SCROLL_UP:   ExecuteScroll(-1),
 	token.SCROLL_DOWN: ExecuteScroll(1),
 	token.HIDE:        ExecuteHide,
diff --git a/command_test.go b/command_test.go
index 19ddc98a..09892449 100644
--- a/command_test.go
+++ b/command_test.go
@@ -8,12 +8,12 @@ import (
 )
 
 func TestCommand(t *testing.T) {
-	const numberOfCommands = 31
+	const numberOfCommands = 43
 	if len(parser.CommandTypes) != numberOfCommands {
 		t.Errorf("Expected %d commands, got %d", numberOfCommands, len(parser.CommandTypes))
 	}
 
-	const numberOfCommandFuncs = 31
+	const numberOfCommandFuncs = 43
 	if len(CommandFuncs) != numberOfCommandFuncs {
 		t.Errorf("Expected %d commands, got %d", numberOfCommandFuncs, len(CommandFuncs))
 	}
diff --git a/lexer/lexer_test.go b/lexer/lexer_test.go
index fd637a72..03682357 100644
--- a/lexer/lexer_test.go
+++ b/lexer/lexer_test.go
@@ -384,3 +384,35 @@ func TestLexTapeFile(t *testing.T) {
 		}
 	}
 }
+
+func TestFunctionKeys(t *testing.T) {
+	input := "F1\nF3 2\nF12@500ms 3\n"
+
+	tests := []struct {
+		expectedType    token.Type
+		expectedLiteral string
+	}{
+		{token.F1, "F1"},
+		{token.F3, "F3"},
+		{token.NUMBER, "2"},
+		{token.F12, "F12"},
+		{token.AT, "@"},
+		{token.NUMBER, "500"},
+		{token.MILLISECONDS, "ms"},
+		{token.NUMBER, "3"},
+	}
+
+	l := New(input)
+
+	for i, tt := range tests {
+		tok := l.NextToken()
+
+		if tok.Type != tt.expectedType {
+			t.Fatalf("tests[%d] - tokentype wrong. expected=%q, got=%q", i, tt.expectedType, tok.Type)
+		}
+
+		if tok.Literal != tt.expectedLiteral {
+			t.Fatalf("tests[%d] - literal wrong. expected=%q, got=%q", i, tt.expectedLiteral, tok.Literal)
+		}
+	}
+}
diff --git a/man.go b/man.go
index 816343b2..9ad6b8b2 100644
--- a/man.go
+++ b/man.go
@@ -41,6 +41,7 @@ The following is a list of all possible commands in VHS:
 * %Up% [repeat]
 * %PageUp% [repeat]
 * %PageDown% [repeat]
+* %F1%-%F12% [repeat]
 * %ScrollUp% [repeat]
 * %ScrollDown% [repeat]
 * %Hide%
diff --git a/parser/parser.go b/parser/parser.go
index 39a4dcb4..2ebdb555 100644
--- a/parser/parser.go
+++ b/parser/parser.go
@@ -52,6 +52,18 @@ var CommandTypes = []CommandType{
 	token.TAB,
 	token.TYPE,
 	token.UP,
+	token.F1,
+	token.F2,
+	token.F3,
+	token.F4,
+	token.F5,
+	token.F6,
+	token.F7,
+	token.F8,
+	token.F9,
+	token.F10,
+	token.F11,
+	token.F12,
 	token.WAIT,
 	token.SOURCE,
 	token.SCREENSHOT,
@@ -151,7 +163,19 @@ func (p *Parser) parseCommand() []Command {
 		token.PAGE_UP,
 		token.PAGE_DOWN,
 		token.SCROLL_UP,
-		token.SCROLL_DOWN:
+		token.SCROLL_DOWN,
+		token.F1,
+		token.F2,
+		token.F3,
+		token.F4,
+		token.F5,
+		token.F6,
+		token.F7,
+		token.F8,
+		token.F9,
+		token.F10,
+		token.F11,
+		token.F12:
 		return []Command{p.parseKeypress(p.cur.Type)}
 	case token.SET:
 		return []Command{p.parseSet()}
diff --git a/parser/parser_test.go b/parser/parser_test.go
index fd3a4467..c5102216 100644
--- a/parser/parser_test.go
+++ b/parser/parser_test.go
@@ -229,6 +229,41 @@ func TestParseTapeFile(t *testing.T) {
 	}
 }
 
+func TestParseFunctionKeys(t *testing.T) {
+	input := "F1\nF3 2\nF12@1s 3\n"
+
+	expected := []Command{
+		{Type: token.F1, Options: "", Args: "1"},
+		{Type: token.F3, Options: "", Args: "2"},
+		{Type: token.F12, Options: "1s", Args: "3"},
+	}
+
+	l := lexer.New(input)
+	p := New(l)
+
+	cmds := p.Parse()
+
+	if errs := p.Errors(); len(errs) > 0 {
+		t.Fatalf("unexpected parser errors: %v", errs)
+	}
+
+	if len(cmds) != len(expected) {
+		t.Fatalf("Expected %d commands, got %d", len(expected), len(cmds))
+	}
+
+	for i, cmd := range cmds {
+		if cmd.Type != expected[i].Type {
+			t.Errorf("Expected command %d to be %s, got %s", i, expected[i].Type, cmd.Type)
+		}
+		if cmd.Args != expected[i].Args {
+			t.Errorf("Expected command %d to have args %s, got %s", i, expected[i].Args, cmd.Args)
+		}
+		if cmd.Options != expected[i].Options {
+			t.Errorf("Expected command %d to have options %s, got %s", i, expected[i].Options, cmd.Options)
+		}
+	}
+}
+
 func TestParseCtrl(t *testing.T) {
 	tests := []struct {
 		name     string
diff --git a/record.go b/record.go
index 838c53f7..906428d7 100644
--- a/record.go
+++ b/record.go
@@ -23,43 +23,55 @@ const sleepThreshold = 500 * time.Millisecond
 
 // EscapeSequences is a map of escape sequences to their VHS commands.
 var EscapeSequences = map[string]string{
-	"\x1b[A":  token.UP,
-	"\x1b[B":  token.DOWN,
-	"\x1b[C":  token.RIGHT,
-	"\x1b[D":  token.LEFT,
-	"\x1b[1~": token.HOME,
-	"\x1b[2~": token.INSERT,
-	"\x1b[3~": token.DELETE,
-	"\x1b[4~": token.END,
-	"\x1b[5~": token.PAGE_UP,
-	"\x1b[6~": token.PAGE_DOWN,
-	"\x01":    token.CTRL + "+A",
-	"\x02":    token.CTRL + "+B",
-	"\x03":    token.CTRL + "+C",
-	"\x04":    token.CTRL + "+D",
-	"\x05":    token.CTRL + "+E",
-	"\x06":    token.CTRL + "+F",
-	"\x07":    token.CTRL + "+G",
-	"\x08":    token.BACKSPACE,
-	"\x09":    token.TAB,
-	"\x0b":    token.CTRL + "+K",
-	"\x0c":    token.CTRL + "+L",
-	"\x0d":    token.ENTER,
-	"\x0e":    token.CTRL + "+N",
-	"\x0f":    token.CTRL + "+O",
-	"\x10":    token.CTRL + "+P",
-	"\x11":    token.CTRL + "+Q",
-	"\x12":    token.CTRL + "+R",
-	"\x13":    token.CTRL + "+S",
-	"\x14":    token.CTRL + "+T",
-	"\x15":    token.CTRL + "+U",
-	"\x16":    token.CTRL + "+V",
-	"\x17":    token.CTRL + "+W",
-	"\x18":    token.CTRL + "+X",
-	"\x19":    token.CTRL + "+Y",
-	"\x1a":    token.CTRL + "+Z",
-	"\x1b":    token.ESCAPE,
-	"\x7f":    token.BACKSPACE,
+	"\x1b[A":   token.UP,
+	"\x1b[B":   token.DOWN,
+	"\x1b[C":   token.RIGHT,
+	"\x1b[D":   token.LEFT,
+	"\x1b[1~":  token.HOME,
+	"\x1b[2~":  token.INSERT,
+	"\x1b[3~":  token.DELETE,
+	"\x1b[4~":  token.END,
+	"\x1b[5~":  token.PAGE_UP,
+	"\x1b[6~":  token.PAGE_DOWN,
+	"\x1bOP":   token.F1,
+	"\x1bOQ":   token.F2,
+	"\x1bOR":   token.F3,
+	"\x1bOS":   token.F4,
+	"\x1b[15~": token.F5,
+	"\x1b[17~": token.F6,
+	"\x1b[18~": token.F7,
+	"\x1b[19~": token.F8,
+	"\x1b[20~": token.F9,
+	"\x1b[21~": token.F10,
+	"\x1b[23~": token.F11,
+	"\x1b[24~": token.F12,
+	"\x01":     token.CTRL + "+A",
+	"\x02":     token.CTRL + "+B",
+	"\x03":     token.CTRL + "+C",
+	"\x04":     token.CTRL + "+D",
+	"\x05":     token.CTRL + "+E",
+	"\x06":     token.CTRL + "+F",
+	"\x07":     token.CTRL + "+G",
+	"\x08":     token.BACKSPACE,
+	"\x09":     token.TAB,
+	"\x0b":     token.CTRL + "+K",
+	"\x0c":     token.CTRL + "+L",
+	"\x0d":     token.ENTER,
+	"\x0e":     token.CTRL + "+N",
+	"\x0f":     token.CTRL + "+O",
+	"\x10":     token.CTRL + "+P",
+	"\x11":     token.CTRL + "+Q",
+	"\x12":     token.CTRL + "+R",
+	"\x13":     token.CTRL + "+S",
+	"\x14":     token.CTRL + "+T",
+	"\x15":     token.CTRL + "+U",
+	"\x16":     token.CTRL + "+V",
+	"\x17":     token.CTRL + "+W",
+	"\x18":     token.CTRL + "+X",
+	"\x19":     token.CTRL + "+Y",
+	"\x1a":     token.CTRL + "+Z",
+	"\x1b":     token.ESCAPE,
+	"\x7f":     token.BACKSPACE,
 }
 
 // Record is a command that starts a pseudo-terminal for the user to begin
diff --git a/token/token.go b/token/token.go
index d0d98a1a..01dc1b53 100644
--- a/token/token.go
+++ b/token/token.go
@@ -60,6 +60,19 @@ const (
 	TAB         = "TAB"
 	SHIFT       = "SHIFT"
 
+	F1  = "F1"
+	F2  = "F2"
+	F3  = "F3"
+	F4  = "F4"
+	F5  = "F5"
+	F6  = "F6"
+	F7  = "F7"
+	F8  = "F8"
+	F9  = "F9"
+	F10 = "F10"
+	F11 = "F11"
+	F12 = "F12"
+
 	COMMENT = "COMMENT"
 	NUMBER  = "NUMBER"
 	STRING  = "STRING"
@@ -136,6 +149,18 @@ var Keywords = map[string]Type{
 	"Tab":           TAB,
 	"Escape":        ESCAPE,
 	"End":           END,
+	"F1":            F1,
+	"F2":            F2,
+	"F3":            F3,
+	"F4":            F4,
+	"F5":            F5,
+	"F6":            F6,
+	"F7":            F7,
+	"F8":            F8,
+	"F9":            F9,
+	"F10":           F10,
+	"F11":           F11,
+	"F12":           F12,
 	"Hide":          HIDE,
 	"Require":       REQUIRE,
 	"Show":          SHOW,
@@ -190,6 +215,7 @@ func IsCommand(t Type) bool {
 	case TYPE, SLEEP,
 		UP, DOWN, RIGHT, LEFT, PAGE_UP, PAGE_DOWN, SCROLL_UP, SCROLL_DOWN,
 		ENTER, BACKSPACE, DELETE, TAB,
+		F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
 		ESCAPE, HOME, INSERT, END, CTRL, SOURCE, SCREENSHOT, COPY, PASTE, WAIT:
 		return true
 	default: