quickstart.txt

TypeText Quick Start
====================

TypeText stores reusable snippets of text and types them into other apps.
Keep it running in the background, open it with a hotkey, choose or queue
snippets, then click the target text field.


1. First Run
------------

Windows:
- Choose the Windows installer, standard portable ZIP, or offline portable ZIP.
- The installer stores data in your normal per-user AppData folder.
- Standard portable stores data beside TypeText.exe and includes update checks
  and optional Open on Startup support.
- Offline portable is the stripped-down option for controlled or disconnected
  environments. It stores data beside TypeText.exe and does not include update
  checks, external update links, or startup registration.
- Run TypeText.exe or install TypeText with the Windows installer.
- TypeText can stay running in the tray.
- Except in offline portable, use Settings > Open on Startup if you want it to
  launch with Windows.
- All Windows versions are native applications. They use Windows features for
  the global hotkey, returning focus to the target window, and typing Unicode
  text; they do not bundle a browser engine or web application runtime.

macOS:
- Open TypeText.app.
- macOS will require Accessibility permission before TypeText can type into
  other apps.
- Go to:
  System Settings > Privacy & Security > Accessibility
- Enable TypeText. If you are running a development build from Terminal, enable
  the terminal app that launched TypeText.
- Use Settings > Open on Startup if you want it to launch when you sign in.


2. Opening TypeText
-------------------

Default hotkey:
Ctrl+Alt+Space

You can change this in Settings > Hotkey. After capturing or editing a hotkey,
click Save Settings.

Up to ten favourite snippets can also have direct-insertion hotkeys. Configure
these under Settings > Favourites. Favourite hotkeys work only while TypeText is
running and must not duplicate the chooser hotkey or one another.

TypeText can also be opened from the tray/menu bar icon.

The app window uses its own top-right controls:
- Min hides TypeText to the background.
- Max toggles the window between normal and maximized size.
- Exit quits TypeText.


3. Adding Snippets
------------------

Open the Edit tab.

Groups:
- Click Add in the Groups area to create a group.
- Click an existing group to edit its name.
- Group details only appear after you click or add a group.

Snippets:
- Open Snippets, choose the active group from the header dropdown, then click
  Add to create a snippet.
- Click an existing snippet to edit it.
- The snippet editor only appears after you click or add a snippet.
- Click Save after changing a snippet.
- Use Favourite beside Add to assign the selected snippet to slot 1-10, or to
  remove its assignment. Reassigning an occupied slot asks for confirmation.
- Favourite snippets show a muted #1-#10 marker in Edit and Choose.
- Use Copy to duplicate the selected snippet into another group.
- Use Move to transfer the selected snippet completely into another group.
- Use Tokens in the Snippet Details header to insert a token at the body cursor
  or replace selected body text.
- Choose Custom, A-Z, or Z-A from Order for each group.
- In Custom order, select a snippet and use Earlier or Later to arrange it.

Tokens:
- Open Tokens and use the header dropdown to switch the sidebar between Custom
  Tokens and Static Tokens.
- Static tokens show built-in date and time token responses.
- Custom tokens can be added, edited, saved, deleted, and reordered.


4. Typing Snippets
------------------

Open the Choose tab.

- Search for a snippet or filter by group.
- Click a snippet to add it to the queue.
- Click a queued snippet again to add it again, or change that behavior in
  Settings > Selection.
- Once your snippets are queued, click the text field in the target app.
- TypeText will hide, restore focus to the target app, and type the queued text.

Favourite hotkeys:
- Configure an optional shortcut for each numbered slot in Settings > Favourites.
- Pressing one types that favourite directly into the previously focused app.
- Moving or reordering a favourite retains its slot.
- Copying or duplicating a favourite does not copy its slot.
- Deleting the snippet frees its slot.

Queue controls:
- Undo Last removes the most recently queued snippet.
- Clear empties the queue.


5. Dynamic Date And Time Tokens
-------------------------------

TypeText expands these tokens immediately before typing, using the computer's
local time zone:

- {time.today}      Current time (legacy DropText alias), for example 17:42
- {time.now}        Current time, for example 17:42
- {date.today}      Today's date, for example 20/06/2026
- {date.tomorrow}   Tomorrow's date, for example 21/06/2026
- {date.yesterday}  Yesterday's date, for example 19/06/2026
- {datetime.now}    Current date and time, for example 20/06/2026 17:42
- {weekday.today}   Current weekday, for example Saturday

Tokens work in imported and manually created snippets. Queued snippets share
one timestamp, and the saved snippet text is not changed. Unknown tokens are
typed unchanged.

In the snippet editor, use the Tokens menu in the Snippet Details header to
insert a token at the body cursor or replace selected body text.

Static date and time token descriptions are stored in tokens.json under
staticTokens. Custom reusable values are stored in the same file under
customTokens.

To add a custom token, open Edit > Tokens, choose Custom Tokens from the header
dropdown, click Add, then set a name and value. For example, set
program.version to 2.4.1, then use
{program.version} in any snippet. When the version changes, update it once in
Tokens and every snippet will use the new value the next time it is typed.

To type a supported token literally, double the braces. For example:
{{date.today}} types {date.today}


6. Paragraph Separators
-----------------------

Settings > Typing includes options for queued snippets:

- Start each queued snippet on a new line
- Empty lines between snippets

Example:
- 0 empty lines means the next snippet starts on the next line.
- 1 empty line means there is a blank line between snippets.


7. Timing Settings
------------------

Delay before typing:
- This waits after TypeText hides and before typing starts.
- Increase it if TypeText starts typing before the target app is focused.

Windows-only delays:
- Windows character delay controls the pause between normal typed characters.
- Windows separator delay controls the pause after spaces, punctuation, tabs,
  and newlines.
- Defaults are 22ms and 35ms.
- On faster machines you may be able to reduce these, for example to 12-18ms.
- If typing becomes unreliable, use Reset to Default.

macOS:
- macOS does not currently expose per-character typing delay. It uses the
  general Delay before typing setting.


8. Settings
-----------

Most Settings changes are staged. If you see:
Unsaved changes - click Save Settings

click Save Settings before leaving the app.

Settings include:
- Hotkey
- Open on Startup (not included in Windows offline portable)
- Delay before typing
- Queue paragraph separator behavior
- Favourite slots 1-10 and their optional direct-insertion hotkeys
- Theme
- Accent color
- Update checks (not included in Windows offline portable)


9. Import, Export, And Data
---------------------------

Settings > Snippet Data:
- Import can bring in DropText INI or CSV snippets.
- Export saves TypeText snippets as JSON.
- Clear All removes all snippets.

Settings > Storage:
- Shows the folder where TypeText stores snippets.json, settings.json, and
  tokens.json.
- Open Data opens that folder.

Installed builds use normal per-user data folders.
Portable Windows builds store data beside TypeText.exe in a data folder.
Offline portable Windows builds never fall back to AppData. Keep TypeText.exe
and its data folder in a location where the user has write access.

The offline portable build refuses UNC and mapped network locations for its data
folder, imports, and exports. Its snippets are readable JSON, not encrypted.
Keep the complete TypeText folder private and do not use TypeText to store
passwords, recovery codes, API keys, or other secrets. Review imported snippets
before using them because snippets can type arbitrary text and Enter keys.

The offline portable build is intentionally lean from a security perspective:
its update, external update-link, and Windows startup-registration features are
removed when the app is built, rather than simply switched off in Settings.
This reduces its network-facing and persistence-related capabilities. TypeText
contains no application network or update functionality; it does not disable
networking in Windows or other applications. Windows may independently perform
background system, connectivity, time, update, or certificate-validation
traffic while TypeText is running. That operating-system traffic is not
initiated by TypeText. TypeText still uses the native Windows features needed
for runtime hotkeys, verified target focus, and text insertion. Favourite
hotkeys do not use the Windows Registry.


10. Troubleshooting And FAQ
---------------------------

TypeText opens but does not type:
- macOS: confirm Accessibility permission is enabled.
- Windows/macOS: increase Delay before typing.
- Make sure you click the target text field after queuing snippets.
- Some secure password fields may block synthetic typing.

TypeText types into the wrong app:
- Queue the snippet first, then click the exact target text field.
- Increase Delay before typing if the previous app is being restored too slowly.
- Avoid clicking another window after choosing the snippet.

Hotkey does not work:
- Try a different hotkey in Settings.
- Click Save Settings after changing it.
- Make sure TypeText is still running in the tray/menu bar.
- Another app may already be using the same hotkey.
- Chooser and favourite hotkeys must all be unique.
- A favourite hotkey needs both a configured shortcut and an assigned snippet.

Settings changed but did not stick:
- Most Settings changes are staged.
- If you see "Unsaved changes - click Save Settings", click Save Settings.
- For hotkey changes, always click Save Settings after capture or manual edit.

TypeText disappeared:
- Min hides TypeText to the background.
- Open it again with the hotkey or tray/menu bar icon.
- Exit fully quits TypeText.

Typing is too slow on Windows:
- Reduce Windows character delay slightly.
- Reduce Windows separator delay slightly.
- Test in the apps you actually use.

Typing misses characters on Windows:
- Increase Windows character delay.
- Increase Windows separator delay.
- Use Reset to Default if needed.

Letters type but spaces are missing on Windows:
- Increase Windows separator delay first.
- Separator delay affects spaces, punctuation, tabs, and newlines.
- Try 50-75ms, test in the target app, then adjust up or down.
- If letters are typing correctly, you usually do not need to increase
  Windows character delay.

Punctuation, tabs, or newlines are missing on Windows:
- Increase Windows separator delay.
- Separator delay covers spaces, punctuation, tabs, and newlines.

Text starts typing before the target app is ready:
- Increase Delay before typing.
- This gives TypeText more time to hide and restore focus to the target app.

Custom tokens do not update existing snippets:
- This is expected. Snippets store token names such as {company.name}.
- The custom token value is expanded only when TypeText types the snippet.
- Update the custom token once in Edit > Tokens > Custom Tokens.

The Tokens list is showing the wrong kind of token:
- In Edit > Tokens, use the header dropdown to switch between Custom Tokens and
  Static Tokens.

The Snippets list is showing the wrong group:
- In Edit > Snippets, use the header dropdown to choose the active group.

Open on Startup is missing:
- It is not included in the Windows offline portable build.
- Use the installer or standard portable build if you need startup registration.

Import or export fails in offline portable:
- Keep TypeText.exe and its data folder on local writable storage.
- Offline portable refuses UNC paths, mapped network drives, and remote import
  or export locations.

Where are my files stored?
- Installed builds use the normal per-user app data folder.
- Portable Windows builds use the data folder beside TypeText.exe.
- Settings > Storage shows the active folder.


11. Recommended First Setup
---------------------------

1. Open TypeText.
2. Set your preferred hotkey.
3. Enable Open on Startup if wanted and available in your build.
4. Add your snippet groups and snippets in Edit.
5. Choose a theme and accent color.
6. Click Save Settings.
7. Open another app, queue a snippet in Choose, click the target field, and
   confirm typing works.