Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ All notable changes to Team Tracker are documented here, written for people usin

See [CLAUDE.md](CLAUDE.md#changelog) for how and when to update this file.

## [3.6.2] - 2026-11-07

### Changed
- The "file could not be written" dialog has shorter buttons in a clearer order, and when the browser has blocked file access it says where to unblock it.
- Phones, tablets and browsers that cannot write the file themselves (Firefox, Safari) are now pointed to Chrome, Edge or Brave on a desktop.

### Fixed
- "Reopen last" and opening a `.tmv` from the system did nothing when the browser had blocked file access; they now explain how to unblock it and to use Open file… instead.

## [3.6.1] - 2026-11-05

### Changed
Expand Down
13 changes: 10 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,14 +68,21 @@ your machine. Team Tracker doesn't:
([why that matters](#zero-runtime-dependencies)).
- ⌨️ **Keyboard-first** — `Ctrl+Shift+K` fast switch, `Ctrl+F` /
`Ctrl+Shift+F` search, `Alt+1`…`Alt+9` team switching, `Alt+Shift+←/→` pane
history, split-view panes, and shortcuts for every module. Desktop-only by
design: phones and tablets get a notice instead of the app, since mobile
browsers lack the File System Access API the open/save flow depends on.
history, split-view panes, and shortcuts for every module. Built for desktop
Chromium browsers (Chrome, Edge, Brave): phones and tablets get a notice
instead of the app, since mobile browsers lack the File System Access API
the open/save flow depends on.
- 🎨 **Yours to tune** — 12 color palettes, light/dark/system theme, 7 font
stacks, adjustable font size, and pt-BR/en-US locales, all in Settings.

## Getting started

**Requirements:** a desktop computer (Windows, macOS or Linux) with a
Chromium-based browser such as Chrome, Edge or Brave. That is what the app is
built and tested on, and where the `.tmv` file is written silently. Firefox and
Safari run it in a [degraded mode](#faq) (manual export, no silent file writes).
Phones and tablets are not supported.

### Web app (installable)

**<https://fmpallini.github.io/team-tracker/>** is always the latest release.
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "team-tracker",
"version": "3.6.1",
"version": "3.6.2",
"homepage": "https://fmpallini.github.io/team-tracker/",
"repository": "fmpallini/team-tracker",
"private": true,
Expand Down
14 changes: 12 additions & 2 deletions src/core/fs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,16 @@ export const supportsFsApi: boolean = typeof window !== 'undefined' && 'showOpen

export class ExternalChangeError extends Error {}

/**
* The browser did not grant read-write access to a remembered or OS-launched
* file: blocked in the site / installed-app settings, or "Don't allow" in the
* prompt. The two are indistinguishable (both come back as not 'granted'), so
* the caller's message has to cover both. Distinct from `null`, which means
* "nothing to open" (no stored handle) — without it a refusal looked like a
* button that does nothing.
*/
export class FilePermissionError extends Error {}

/**
* Size and SHA-256 of what this session last read from, or wrote to, its file.
* Lets `writeFile` tell a real external edit from a mere mtime bump (cloud-sync
Expand Down Expand Up @@ -124,10 +134,10 @@ export async function pickCreate(suggestedName: string): Promise<FileSession | n
export async function openFromHandle(
handle: FileSystemFileHandle,
persist = true
): Promise<{ session: FileSession; bytes: Uint8Array } | null> {
): Promise<{ session: FileSession; bytes: Uint8Array }> {
let permission = await handle.queryPermission({ mode: 'readwrite' })
if (permission !== 'granted') permission = await handle.requestPermission({ mode: 'readwrite' })
if (permission !== 'granted') return null
if (permission !== 'granted') throw new FilePermissionError()
const { bytes, lastModified } = await readHandle(handle)
const session: FileSession = { handle, name: handle.name, lastModified }
setBaseline(session, bytes)
Expand Down
24 changes: 16 additions & 8 deletions src/core/i18n.ts
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,8 @@ const pt = {
'Navegadores móveis não têm a File System Access API — o app não conseguiria abrir e salvar seu arquivo .tmv diretamente (cada salvamento viraria um novo download)',
mobile_block_reason_ux:
'A interface é feita para teclado e telas grandes — atalhos (Ctrl+Shift+K), visão dividida e painéis densos',
mobile_block_hint: 'Abra em um computador (Windows, macOS ou Linux) para usar o app.',
mobile_block_hint:
'Abra em um computador (Windows, macOS ou Linux) com um navegador baseado em Chromium, como Chrome, Edge ou Brave.',
start_open_ellipsis: 'Abrir arquivo…',
start_create_ellipsis: 'Criar novo…',
start_reopen_ellipsis: 'Reabrir último…',
Expand All @@ -95,7 +96,9 @@ const pt = {
err_invalid_shape: 'Estrutura de arquivo inválida em: {path}',
err_schema_too_new: 'Arquivo criado por uma versão mais nova do app — atualize o app',
err_unexpected: 'Ocorreu um erro inesperado',
fallback_notice: 'Este navegador não consegue gravar o arquivo sozinho. Seu trabalho fica guardado no navegador; use Exportar arquivo, no cabeçalho, para baixar uma cópia.',
err_file_permission:
'O navegador não liberou o acesso a este arquivo. Se a permissão estiver bloqueada, libere-a nas configurações do site (cadeado na barra de endereço) ou, no app instalado, nas configurações do aplicativo. Enquanto isso, use Abrir arquivo… e escolha o arquivo manualmente.',
fallback_notice: 'Este navegador não consegue gravar o arquivo sozinho (só Chrome, Edge e Brave conseguem). Seu trabalho fica guardado no navegador; use Exportar arquivo, no cabeçalho, para baixar uma cópia.',
team_add_title: 'Novo time',
close: 'Fechar',
sidebar_teams_heading: 'Times',
Expand Down Expand Up @@ -618,13 +621,14 @@ sidebar_teams_heading: 'Times',
write_failed_body_permission: 'O navegador perdeu a permissão para gravar o arquivo. Suas alterações estão seguras no navegador: conceda o acesso de novo para gravar o arquivo agora, baixe uma cópia ou feche mesmo assim.',
write_failed_body_error: 'O arquivo não pôde ser gravado. Suas alterações estão seguras no navegador: tente de novo, baixe uma cópia ou feche mesmo assim.',
write_failed_body_store: 'O navegador não conseguiu guardar suas últimas alterações e o arquivo não pôde ser gravado. Baixe uma cópia para não perdê-las, ou tente de novo depois de liberar espaço.',
write_failed_close_discard: 'Fechar e descartar as alterações',
write_failed_close_discard: 'Fechar e descartar',
live_store_failed_toast: 'O navegador não está conseguindo guardar suas alterações (talvez falte espaço). Por enquanto elas existem só na memória desta aba: libere espaço ou clique no indicador para baixar uma cópia.',
write_failed_regrant: 'Conceder acesso…',
write_failed_download: 'Baixar uma cópia',
write_failed_retry: 'Tentar de novo',
write_failed_close_anyway: 'Fechar mesmo assim — o navegador guarda seu trabalho',
write_failed_close_anyway: 'Fechar mesmo assim',
write_failed_still: 'Ainda não foi possível gravar o arquivo.',
write_failed_still_permission: 'O acesso não foi concedido. Se estiver bloqueado, libere-o nas configurações do site (cadeado na barra de endereço) ou, no app instalado, nas configurações do aplicativo.',
close_browser_copy_failed_toast: 'O arquivo foi gravado, mas este navegador não conseguiu guardar a própria cópia do documento.',
save_permission_toast: 'O navegador perdeu a permissão para gravar o arquivo — suas alterações continuam seguras no navegador',
grant_access_ellipsis: 'Conceder acesso…',
Expand Down Expand Up @@ -771,7 +775,8 @@ const en: Record<MsgKey, string> = {
"Mobile browsers lack the File System Access API — the app couldn't open and save your .tmv file directly (every save would become a new download)",
mobile_block_reason_ux:
'The interface is built for keyboard and large screens — shortcuts (Ctrl+Shift+K), split view, dense panes',
mobile_block_hint: 'Open it on a desktop computer (Windows, macOS or Linux) to use the app.',
mobile_block_hint:
'Open it on a desktop computer (Windows, macOS or Linux) with a Chromium-based browser such as Chrome, Edge or Brave.',
start_open_ellipsis: 'Open file…',
start_create_ellipsis: 'Create new…',
start_reopen_ellipsis: 'Reopen last…',
Expand All @@ -796,7 +801,9 @@ const en: Record<MsgKey, string> = {
err_invalid_shape: 'Invalid file structure at: {path}',
err_schema_too_new: 'File created by a newer version of the app — please update the app',
err_unexpected: 'An unexpected error occurred',
fallback_notice: 'This browser cannot write the file by itself. Your work is kept in the browser; use Export file in the header to download a copy.',
err_file_permission:
'The browser has not granted access to this file. If the permission is blocked, allow it in the site settings (padlock in the address bar) or, in the installed app, in the app settings. In the meantime, use Open file… and pick the file manually.',
fallback_notice: 'This browser cannot write the file by itself (only Chrome, Edge and Brave can). Your work is kept in the browser; use Export file in the header to download a copy.',
team_add_title: 'New team',
close: 'Close',
sidebar_teams_heading: 'Teams',
Expand Down Expand Up @@ -1308,13 +1315,14 @@ sidebar_teams_heading: 'Teams',
write_failed_body_permission: 'The browser lost permission to write the file. Your changes are safe in the browser: grant access again to write the file now, download a copy, or close anyway.',
write_failed_body_error: 'The file could not be written. Your changes are safe in the browser: try again, download a copy, or close anyway.',
write_failed_body_store: 'The browser could not store your latest changes, and the file could not be written. Download a copy so they are not lost, or try again after freeing up space.',
write_failed_close_discard: 'Close and discard the changes',
write_failed_close_discard: 'Close and discard',
live_store_failed_toast: 'The browser cannot store your changes right now (it may be out of space). For now they exist only in memory in this tab: free up space, or click the indicator to download a copy.',
write_failed_regrant: 'Grant access…',
write_failed_download: 'Download a copy',
write_failed_retry: 'Try again',
write_failed_close_anyway: 'Close anyway — the browser keeps your work',
write_failed_close_anyway: 'Close anyway',
write_failed_still: 'The file still could not be written.',
write_failed_still_permission: 'Access was not granted. If it is blocked, allow it in the site settings (padlock in the address bar) or, in the installed app, in the app settings.',
close_browser_copy_failed_toast: 'The file was written, but this browser could not keep its own copy of the document.',
save_permission_toast: 'The browser lost permission to write the file — your changes are still safe in the browser',
grant_access_ellipsis: 'Grant access…',
Expand Down
14 changes: 13 additions & 1 deletion src/ui/start.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import {
downloadFallback,
openFromHandle,
peekLastFile,
FilePermissionError,
type FileSession,
} from '../core/fs'
import { idbGet, idbSet } from '../core/idb'
Expand Down Expand Up @@ -176,7 +177,18 @@ export function showStartScreen(
// for a password.
async function openAndDecrypt(fetchResult: () => Promise<{ session: FileSession; bytes: Uint8Array } | null>): Promise<void> {
openStarted = true
const result = await fetchResult()
let result: { session: FileSession; bytes: Uint8Array } | null
try {
result = await fetchResult()
} catch (e) {
// A refused grant on a remembered / OS-launched file: say so and point at
// the manual open, which always works (its picker is its own gesture).
if (e instanceof FilePermissionError) {
showErrorModal(locale, t(locale, 'err_file_permission'))
return
}
throw e
}
if (!result) return
let plain: OpenedDoc | null
try {
Expand Down
16 changes: 11 additions & 5 deletions src/ui/write-failed.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,11 @@ export function showWriteFailedDialog(opts: WriteFailedOptions): Promise<'closed
let busy = false

/** Runs an async fix; a fix that did not work leaves the dialog up with a note, a working one resolves. */
const attempt = (fix: () => Promise<boolean>): void => {
const attempt = (fix: () => Promise<boolean>, stillKey: 'write_failed_still' | 'write_failed_still_permission'): void => {
if (busy) return
busy = true
still.hidden = true
still.textContent = t(locale, stillKey)
fix()
.then((ok) => {
if (ok) { finish('resolved'); handle.close() } else still.hidden = false
Expand All @@ -58,13 +59,18 @@ export function showWriteFailedDialog(opts: WriteFailedOptions): Promise<'closed
if (opts.allowCloseAnyway !== false) {
buttons.push({ label: t(locale, opts.copyFailed ? 'write_failed_close_discard' : 'write_failed_close_anyway'), danger: true, left: true, onClick: () => { finish('closed-anyway'); handle.close() } })
}
// Left: the way out. Right, in reading order: the side action (a copy), stay, then the fix — the primary, last.
// Re-granting already writes the file once the permission is held, so a separate "Try again" next to it could only
// fail again for the same reason; it stays for every failure that has nothing to re-grant.
const regrant = opts.reason === 'permission' && opts.canRegrant
buttons.push(
{ label: t(locale, 'cancel'), icon: 'close', onClick: () => { finish('cancelled'); handle.close() } },
{ label: t(locale, 'write_failed_download'), onClick: () => opts.onDownload() },
{ label: t(locale, 'write_failed_retry'), primary: !(opts.reason === 'permission' && opts.canRegrant), onClick: () => attempt(() => opts.onRetry()) },
{ label: t(locale, 'cancel'), icon: 'close', onClick: () => { finish('cancelled'); handle.close() } },
)
if (opts.reason === 'permission' && opts.canRegrant) {
buttons.push({ label: t(locale, 'write_failed_regrant'), primary: true, onClick: () => attempt(() => opts.onRegrant()) })
if (regrant) {
buttons.push({ label: t(locale, 'write_failed_regrant'), primary: true, onClick: () => attempt(() => opts.onRegrant(), 'write_failed_still_permission') })
} else {
buttons.push({ label: t(locale, 'write_failed_retry'), primary: true, onClick: () => attempt(() => opts.onRetry(), 'write_failed_still') })
}

const bodyKey = opts.copyFailed ? 'write_failed_body_store' : opts.reason === 'permission' ? 'write_failed_body_permission' : 'write_failed_body_error'
Expand Down
2 changes: 1 addition & 1 deletion styles.css
Original file line number Diff line number Diff line change
Expand Up @@ -645,7 +645,7 @@ body { background: var(--bg); color: var(--fg); }
background: color-mix(in srgb, var(--danger) 10%, var(--panel));
color: var(--danger); font-weight: 600;
}
.tt-modal-buttons { display: flex; justify-content: flex-end; gap: .5rem; margin-top: .5rem; }
.tt-modal-buttons { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: .5rem; margin-top: .5rem; }
.tt-password-form { display: flex; flex-direction: column; gap: .75rem; }
.tt-editor-link-form { display: flex; flex-direction: column; gap: .75rem; }
.tt-field { display: flex; flex-direction: column; gap: .25rem; font-size: .9rem; color: var(--muted); }
Expand Down
15 changes: 11 additions & 4 deletions test/fs.test.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { writeFile, forceWrite, openFromHandle, reopenLast, peekLastFile, sameEntry, pickCreate, pickOpen, readCurrent, downloadFallback, ExternalChangeError, type FileSession } from '../src/core/fs'
import { writeFile, forceWrite, openFromHandle, reopenLast, peekLastFile, sameEntry, pickCreate, pickOpen, readCurrent, downloadFallback, ExternalChangeError, FilePermissionError, type FileSession } from '../src/core/fs'

function mockHandle(initialMtime: number, permission?: PermissionState) {
let mtime = initialMtime
Expand Down Expand Up @@ -115,10 +115,17 @@ test('openFromHandle requests permission when not yet granted, then reads', asyn
expect(result!.bytes).toEqual(new Uint8Array([7]))
})

test('openFromHandle returns null when permission is denied', async () => {
test('openFromHandle throws FilePermissionError when permission is denied, without reading the file', async () => {
const handle = mockLaunchHandle('denied')
const result = await openFromHandle(handle)
expect(result).toBeNull()
const getFile = vi.spyOn(handle, 'getFile')
await expect(openFromHandle(handle)).rejects.toBeInstanceOf(FilePermissionError)
expect(getFile).not.toHaveBeenCalled()
})

test('openFromHandle throws FilePermissionError when the prompt is dismissed without a grant', async () => {
const handle = mockLaunchHandle('prompt')
;(handle.requestPermission as ReturnType<typeof vi.fn>).mockResolvedValueOnce('prompt')
await expect(openFromHandle(handle)).rejects.toBeInstanceOf(FilePermissionError)
})

test('openFromHandle persists the handle to lastHandle by default (the File Handling API launch path)', async () => {
Expand Down
1 change: 1 addition & 0 deletions test/start-live.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import type { FileSession } from '../src/core/fs'
import type { Doc } from '../src/core/types'

const fsMocks = vi.hoisted(() => ({
FilePermissionError: class FilePermissionError extends Error {},
supportsFsApi: true,
pickOpen: vi.fn(),
pickCreate: vi.fn(),
Expand Down
39 changes: 38 additions & 1 deletion test/start.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { FileSession } from '../src/core/fs'
import type { OpenedDocument } from '../src/ui/open-document'

const fsMocks = vi.hoisted(() => ({
FilePermissionError: class FilePermissionError extends Error {},
supportsFsApi: true,
pickOpen: vi.fn(),
pickCreate: vi.fn(),
Expand Down Expand Up @@ -198,6 +199,42 @@ test('file handling launch: fetchResult resolving null (e.g. picker cancel) is a
expect(document.querySelector('input[name="tt-password"]')).toBeNull()
})

test('a browser without the File System Access API is told which browsers can write the file itself', async () => {
fsMocks.supportsFsApi = false
showStartScreen('en-US', () => {})
await flush()
expect(document.querySelector('.tt-start-fallback-notice')?.textContent).toContain('Chrome, Edge')
})

test('reopen-last: a denied file permission explains how to unblock it and to open manually, instead of doing nothing', async () => {
idbMocks.idbGet.mockImplementation(async () => ({}) as unknown)
fsMocks.reopenLast.mockRejectedValue(new fsMocks.FilePermissionError())

const onOpen = vi.fn()
showStartScreen('en-US', onOpen)
await flush()
clickByText('Reopen last…')
await flush()

const message = document.querySelector('.tt-modal-message')?.textContent ?? ''
expect(message).toContain('site settings')
expect(message).toContain('installed app')
expect(message).toContain('Open file…')
expect(onOpen).not.toHaveBeenCalled()
})

test('file handling launch: a denied file permission shows the same explanation', async () => {
const getConsumer = mockLaunchQueue()
fsMocks.openFromHandle.mockRejectedValue(new fsMocks.FilePermissionError())

showStartScreen('pt-BR', () => {})
await flush()
getConsumer()({ files: [{} as unknown as FileSystemFileHandle] })
await flush()

expect(document.querySelector('.tt-modal-message')?.textContent).toContain('configurações do site')
})

test('open flow: wrong password loops until correct, then calls onOpen', async () => {
const session: FileSession = { handle: null, name: 'x.tmv', lastModified: 1 }
const bytes = new Uint8Array([9])
Expand Down Expand Up @@ -448,7 +485,7 @@ test('fallback mode (no FS API): open uses hidden file input', async () => {
showStartScreen('en-US', () => {})
await flush()
expect(document.querySelector('.tt-start-fallback-notice')?.textContent).toBe(
'This browser cannot write the file by itself. Your work is kept in the browser; use Export file in the header to download a copy.'
'This browser cannot write the file by itself (only Chrome, Edge and Brave can). Your work is kept in the browser; use Export file in the header to download a copy.'
)
const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement
expect(fileInput).not.toBeNull()
Expand Down
Loading
Loading