Release v1.3.0

.githooks/README.md

@@ -0,0 +1,28 @@
+# .githooks — versioning enforcement
+
+Git-native hooks (POSIX, no dependencies). They run for **every** commit, whether made by a
+person or by an agent, and enforce the team's versioning rules.
+
+- **`commit-msg`** — rejects the commit if the message is not a Conventional Commit
+  (`<type>(<scope>)(!): description`). Warns (does not block) when the type does not match the
+  branch prefix.
+- **`pre-commit`** — blocks direct commits on `main` or `beta` (development happens on
+  temporary branches). Escape for release promotion: `ATENEA_ALLOW_PROTECTED=1 git commit ...`.
+
+## Activation
+
+`core.hooksPath` is a per-clone local setting (it is not versioned), so each clone enables it
+once. The project automates it with a `prepare` script in `package.json`:
+
+```json
+"scripts": { "prepare": "git config core.hooksPath .githooks || true" }
+```
+
+That way every `npm install` wires it up. Manually, if needed:
+
+```bash
+git config core.hooksPath .githooks
+chmod +x .githooks/*
+```
+
+One-off bypass of a hook (not recommended): `git commit --no-verify`.

.githooks/commit-msg

@@ -0,0 +1,53 @@
+#!/bin/sh
+# ─────────────────────────────────────────────────────────────────────────
+# Atenea · commit-msg · validates Conventional Commits (Venteks versioning manual)
+#
+# Git-native: runs for ANY commit (human or agent), with or without Claude.
+# Blocks the commit if the message does not comply. One-off escape: git commit --no-verify.
+#
+# Required format:  <type>(<optional scope>)(!): <imperative description>
+#   types: feat fix docs style refactor perf test build ci chore revert
+#   examples:  feat(auth): add session login
+#              fix: correct permission calculation
+#              feat(store)!: change the state shape (BREAKING CHANGE)
+# ─────────────────────────────────────────────────────────────────────────
+
+msg_file="$1"
+first_line="$(head -n 1 "$msg_file")"
+
+# Skip automatic merge/revert commits and fixup/squash.
+case "$first_line" in
+  "Merge "*|"Revert "*|"fixup!"*|"squash!"*) exit 0 ;;
+esac
+
+pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?(!)?: .+'
+
+if printf '%s' "$first_line" | grep -Eq "$pattern"; then
+  # Soft warning: type ↔ branch prefix consistency (does not block).
+  # A feat/* branch is a feature container: it legitimately accumulates intermediate
+  # fix/docs/refactor/chore/test commits, so it is NOT warned about. Only fix/* and
+  # hotfix/* are checked, since they have a single purpose.
+  branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo '')"
+  type="$(printf '%s' "$first_line" | sed -E 's/^([a-z]+).*/\1/')"
+  case "$branch" in
+    fix/*)     [ "$type" = "fix" ]  || printf '⚠️  Atenea: fix/* branch but commit "%s" (should it be fix?)\n' "$type" >&2 ;;
+    hotfix/*)  [ "$type" = "fix" ]  || printf '⚠️  Atenea: hotfix/* branch but commit "%s" (should it be fix?)\n' "$type" >&2 ;;
+  esac
+  exit 0
+fi
+
+cat >&2 <<'EOF'
+✕ Atenea · commit rejected: the message does not follow Conventional Commits.
+
+  Format:   <type>(<scope>)(!): <imperative description>
+  Types:    feat fix docs style refactor perf test build ci chore revert
+
+  Valid examples:
+    feat(auth): add session login
+    fix: correct permission calculation
+    feat(store)!: change the state shape
+
+  Team versioning manual (Atenea plugin, git-flow skill).
+  One-off bypass (not recommended):  git commit --no-verify
+EOF
+exit 1

.githooks/pre-commit

@@ -0,0 +1,36 @@
+#!/bin/sh
+# ─────────────────────────────────────────────────────────────────────────
+# Atenea · pre-commit · protects the permanent branches (Venteks versioning manual)
+#
+# Rule: "never develop directly on main". Development happens on temporary branches
+# (feat/ fix/ chore/ docs/) created from beta; hotfix/ from main. This hook blocks
+# DIRECT commits on main or beta.
+#
+# Escape for release promotion/merge:  ATENEA_ALLOW_PROTECTED=1 git commit ...
+# One-off full bypass:                  git commit --no-verify
+# ─────────────────────────────────────────────────────────────────────────
+
+[ "${ATENEA_ALLOW_PROTECTED:-}" = "1" ] && exit 0
+
+branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo '')"
+
+case "$branch" in
+  main|beta)
+    cat >&2 <<EOF
+✕ Atenea · direct commit on '$branch' blocked.
+
+  Development happens on temporary branches:
+    feat/<feature> · fix/<bug> · chore/<task> · docs/<topic>   (from beta)
+    hotfix/<bug>                                                (from main)
+
+  Create the branch and switch to it:
+    git switch -c feat/my-change
+
+  Release promotion (merge into $branch):  ATENEA_ALLOW_PROTECTED=1 git commit ...
+  One-off bypass (not recommended):        git commit --no-verify
+EOF
+    exit 1
+    ;;
+esac
+
+exit 0

.github/workflows/ci.yml

@@ -2,9 +2,10 @@ name: CI
 
 on:
   pull_request:
-    branches: [main]
+    branches: [beta, main]
+    types: [opened, synchronize, reopened, edited]
   push:
-    branches: [main]
+    branches: [beta, main]
 
 concurrency:
   group: ci-${{ github.ref }}

CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [1.3.0] - 2026-11-01
+
+### Added
+
+- Screen reader support (VoiceOver and TalkBack): an invisible adjustable control announces the current page ("Page 3 of 12", or "Pages 3 and 4 of 12" in book mode) and turns pages with the increment/decrement actions. Headings are exposed with the `header` role.
+- `accessibilityLabels` prop on `DocumentViewer` to override the spoken strings, plus the `ViewerAccessibilityLabels` type and the `DEFAULT_ACCESSIBILITY_LABELS` export.
+- GitHub Actions CI for every PR and push to `beta` and `main`: typecheck, lint, formatting and tests. It also reruns when a PR is retargeted.
+- Git hooks (`.githooks/`) that require Conventional Commits and block direct commits on `main` and `beta`, and a contributing guide with the branching model.
+
+### Changed
+
+- Peer dependency ranges now match what the library supports: `react-native` ≥ 0.76, `react` ≥ 18.3.1, `react-native-reanimated` ≥ 3.16 and < 4, `react-native-gesture-handler` ≥ 2.20 and < 3. Reanimated 4 and Gesture Handler 3 are not supported yet.
+- The repository moved from GitLab to GitHub (`acertijosapps/react-native-md-document`): `repository` and `bugs` in `package.json` and `source` in the podspec, which now uses the `vX.Y.Z` tag.
+- The public documentation (README, changelog, contributing guide) is now in English.
+
+### Fixed
+
+- The pages stacked behind the current one for the flip animation are hidden from the accessibility tree, so screen readers no longer read them.
+- The error thrown when the native speech module is not linked now names the published package (`@acertijosapps/react-native-md-document`) instead of the old `react-native-document`, and is in English.
+
+## [1.2.0] - 2026-10-25
+
+### Added
+
+- Book mode: on tablets and foldables in landscape, the document is shown as two facing pages with page-turning. Props `dualPage` (on by default), `dualPageMinWidth` and `spreadGap` (space for a foldable's hinge).
+- `onPageChange` receives a fourth argument, `pagesPerView` (1 or 2).
+- "Book mode" and "Foldables" sections in the README, with screenshots.
+
+### Fixed
+
+- Pagination on tablets: it no longer gets stuck or leaves blank pages because of late layout events.
+- Book mode only turns on for tablet- or foldable-sized screens (window short side of at least 600 dp); a phone in landscape still shows a single page.
+
+## [1.1.2] - 2026-10-13
+
+### Changed
+
+- `author`, email and `homepage` of AcertijosApps in `package.json` and the podspec.
+
+## [1.1.1] - 2026-09-19
+
+### Added
+
+- `homepage`, `repository` and `bugs` in `package.json`, and an aligned podspec.
+
+## [1.1.0] - 2026-09-19
+
+### Added
+
+- Loading the document through `source`, with loading and error states (`onLoad*`, `renderLoading`, `renderError`).
+
+## [1.0.1] - 2026-09-19
+
+### Changed
+
+- README with the published package name and absolute image URLs, so they render on npm; `media/` is included in the package.
+- Podspec renamed to `react-native-md-document.podspec`.
+- Keywords `android`, `ios` and `zoom`.
+
+## [1.0.0] - 2026-09-19
+
+### Added
+
+- First public release: Markdown-as-PDF viewer with page-turning, zoom, persistent highlights, text-to-speech (TTS) and light/dark color tokens, with injectable storage, source and speech engine.

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing
+
+Contributions are welcome. Keep changes small, focused and traceable.
+
+## Development workflow
+
+Use the Node.js version in [`.nvmrc`](./.nvmrc) and install the dependencies from the root:
+
+```sh
+npm install
+```
+
+`npm install` also wires the repository git hooks (`core.hooksPath` → `.githooks/`).
+
+The example app lives in `example/` (Expo) and consumes the code in `src/` directly, so TypeScript changes hot-reload there.
+
+### Commands
+
+```sh
+npm run typecheck     # type-check with TypeScript
+npm run lint          # lint with ESLint
+npm run format        # format with Prettier (writes)
+npm run format:check  # check formatting with Prettier
+npm test              # run the unit tests (node:test)
+```
+
+## Branching model
+
+Two permanent branches, both protected:
+
+- **`main`**: production. No direct pushes; changes land only through an approved Pull Request.
+- **`beta`**: release candidate.
+
+Temporary branches, always created from `beta`, in kebab-case:
+
+- `feat/<name>` · `fix/<name>` · `chore/<name>` · `docs/<name>` → Pull Request **into `beta`**, deleted after merge.
+- `hotfix/<name>` is the only exception: created from `main`, PR into `main`, then back-merged into `beta`.
+
+One branch = one focused change.
+
+## Commits
+
+Write commit messages and Pull Requests in English, following [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<optional scope>)(!): <imperative description>
+```
+
+Types: `feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`.
+
+[SemVer](https://semver.org/) mapping: `feat` → MINOR, `fix` → PATCH, breaking (`feat!` or `BREAKING CHANGE:`) → MAJOR.
+
+The git hooks in [`.githooks/`](./.githooks) run for every commit:
+
+- `commit-msg` rejects messages that are not Conventional Commits.
+- `pre-commit` blocks direct commits on `main` and `beta`.
+
+One-off bypass (not recommended): `git commit --no-verify`.
+
+## Changelog
+
+Any change that affects behavior updates [`CHANGELOG.md`](./CHANGELOG.md) ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/)): add the entry under `## [Unreleased]` in the right category (Added · Changed · Fixed · Removed).
+
+## Pull Requests
+
+When opening a PR:
+
+- Target `beta` (or `main` only for `hotfix`).
+- Keep it small and focused on one change.
+- Request a review when there is another maintainer. Approvals are not enforced while the repository has a single maintainer; the PR and a green CI check are always required.
+- Gates must be green: `npm run typecheck`, `npm run lint`, `npm run format:check` and `npm test`. CI ([`.github/workflows/ci.yml`](./.github/workflows/ci.yml)) runs them on every PR to `beta` or `main`.
+- Include the `CHANGELOG.md` entry.
+
+## Releasing (`beta` → `main`)
+
+1. Confirm the gates are green on `beta`.
+2. Decide the SemVer bump from the commits since the last tag.
+3. Update `version` in `package.json`.
+4. Rename the `## [Unreleased]` section of the changelog to `## [X.Y.Z] - YYYY-MM-DD` and open a fresh empty one.
+5. Open the `beta` → `main` PR and merge it.
+6. Tag `vX.Y.Z` on `main` and push it (`git push origin vX.Y.Z`).
+7. Publish from the repository root with `npm publish` (the README and `package.json` are frozen per version).