Roadmap: adopt high-value upstream fixes and establish compatibility coverage

[darekaze]

Purpose

This is the handoff and execution roadmap for maintaining this fork against the dormant upstream tr3v3r/react-native-esc-pos-printer.

Snapshot date: 2026-08-13. Upstream is not archived, but its last commit and release were v4.5.0 on 2025-10-24. At review time it had 24 open issues and 4 open PRs. The detailed triage is also recorded locally at docs/upstream-backlog-triage.md.

Current fork state

• Fork main currently matches upstream commit 461cd37.
• Fork PR #1 addresses upstream #249 and includes additional printer compatibility corrections.
• Do not implement #249 again. Confirm PR fix: apply printer compatibility patches #1 is landed before starting overlapping Codegen or discovery work.
• PR fix: apply printer compatibility patches #1 also corrects TM-m30 model matching related to upstream #230, though #230's reported connection failure was not conclusively traced to that bug.

Execution order

Each item should normally be a focused PR. Preserve links to the upstream report in the PR body and record the exact verification environment.

1. Fix the invalid p-queue import — upstream #224

Source: upstream #224

Current Printer.initQueue() loads p-queue/dist, but p-queue@7.4.1 exports only its package root. This can fail with ERR_PACKAGE_PATH_NOT_EXPORTED.

• Replace the private subpath with the package's public entry point.
• Verify both source and Bob-built module output load correctly with Metro.
• Add/adjust a test that instantiates and executes queued printer work through the published module shape.
• Confirm no p-queue/dist import remains.

Done when: the built package loads through Metro and serial queue behavior passes without an export-path warning/error.

2. Harden iOS discovery — upstream #248 and #232

Sources: #248, #232

The current onDiscovery: callback reads SDK-owned values, constructs an NSDictionary without nil handling, mutates _printerList, and emits the same mutable object. This is consistent with the reported intermittent EXC_BAD_ACCESS; TYPE_PRINTER also avoids the blank new-architecture error reported in #232.

• Copy SDK-owned strings immediately and coalesce nil values.
• Serialize access using instance-owned synchronization.
• Emit an immutable list snapshot on a safe/main queue.
• Preserve explicit TYPE_ALL; evaluate TYPE_PRINTER as the default separately.
• Review interaction with PR fix: apply printer compatibility patches #1's pairing changes before editing the same file.
• Repeatedly start/stop discovery on iOS new architecture and test discovery with printer-only and all-device filters.

Do not paste #248's process-global static lock verbatim; discovery instances should not share unrelated synchronization state.

Done when: repeated discovery no longer crashes, nil device fields cannot crash dictionary construction, and both filter modes have documented behavior.

3. Define and enforce React Native Codegen compatibility — upstream #245 and #234

Sources: #245, #234, React Native Codegen guidance

The library pins RN 0.81.1 and ships generated output with includesGeneratedCode: true. React Native warns that such output is tied to the library's RN version. The published Android CMake output contains target_compile_reactnative_options, which RN 0.79 does not provide. #234 additionally reports a 32-bit armeabi-v7a new-architecture crash, but its exact cause remains unverified.

• Decide and document the supported RN minimum/maximum.
• Choose one packaging strategy: consumer-generated artifacts, or generated artifacts tested across the supported range.
• Add Android/iOS new-architecture build coverage at the supported range boundaries.
• Reproduce #245 on RN 0.79 before changing packaging, then confirm the selected strategy fixes it.
• Reproduce #234 in a minimal 32-bit app without Reanimated before attributing it to this library.
• Retain #249 coverage from PR fix: apply printer compatibility patches #1 for RN 0.85+ iOS.

Done when: the supported RN range is explicit, boundary builds are automated, #245 is fixed, and #234 is either reproduced/fixed or documented with evidence as unrelated.

4. Diagnose the connection latency regression — upstream #243

Source: upstream #243

The reported boundary is v4.4.4, whose substantive change was the Epson native SDK update to 2.33.1. Multiple users report connect() increasing from under one second to 6–8 seconds on Android and iOS. Epson now lists ePOS SDK 2.37.0a.

• Use identical app, printer, network, and wrapper code to A/B Epson SDK 2.33.1 and 2.37.0a.
• Record at least ten connection timings per SDK/platform/transport tested.
• If needed, compare the pre-v4.4.4 SDK only after the first A/B.
• Identify whether the latency is inside Epson connect, wrapper initialization, discovery, or reconnect behavior.
• Update the bundled SDK only after functional printing/discovery regression checks.

Do not hide the regression by shortening or bypassing the timeout.

Done when: timing evidence identifies the responsible layer and the selected SDK/wrapper behavior restores acceptable latency without losing 16 KB page-size support.

5. Define direct Bluetooth permission ownership — upstream #131

Source: upstream #131

Discovery requests Android permissions internally; direct connection to a known Bluetooth address does not. The issue's suggested deep import is not a stable public API.

• Decide whether the library or caller owns direct-connect permission requests.
• If library-owned, expose a documented public request/check API and test Android API-level branches.
• If caller-owned, document exact manifest and runtime requirements next to direct-connect examples.
• Verify direct connection without first invoking discovery.

Done when: a clean install can connect directly or return a clear permission failure using only documented public APIs.

6. Hardware-gated investigations — upstream #185 and #250

Sources: #185, #250

• #185: verify Android connect(1500) timeout behavior on the current SDK and each supported transport. The current wrapper already forwards the value; do not add JS cancellation before confirming Epson semantics.
• #250: reproduce CODE_ERR_WAIT_REMOVAL on a TM-L90LFC and determine whether the job was accepted, rejected, or is awaiting sensor state.
• Preserve removalWaiting and status mappings already exposed by the library.

Done when: each issue has hardware evidence and a behavior-preserving fix or an explicit SDK/device limitation. Never turn CODE_ERR_WAIT_REMOVAL into success without proving job acceptance semantics; that risks duplicate or lost labels.

7. Optional roadmap feature — upstream PR #241

Source: upstream PR #241

Page mode is useful but the PR implements Android only while changing shared TypeScript APIs.

• Take this only if page mode is a confirmed fork requirement.
• Treat the PR as an Android reference, not a cherry-pick.
• Design and test equivalent iOS behavior before exposing shared methods.

Done when: both platforms implement the shared contract and tests/documentation cover page boundaries, direction, position, begin, and end.

Upstream PR disposition

Do not cherry-pick any currently open upstream PR as-is:

• #242: incomplete rename; changes the setter declaration but leaves its call misspelled.
• #241: Android-only page mode; roadmap reference only.
• #225: outdated layout, iOS-only scanner work, dirty base, no cross-platform contract.
• #169: partial RN Windows 0.74-era port against a non-main branch; reference only if Windows becomes a requirement.

Issues already resolved, unsupported, or deferred

• Already resolved in current fork/upstream code: #193, #105.
• Unsupported third-party printer reports/support questions: #226, #222, #204.
• Reproduce before action: #247, #233, #191, #184, #154, #135, #98.
• Roadmap-only: Windows support #136.

Agent handoff rules

1. Read this issue and docs/upstream-backlog-triage.md before selecting work.
2. Check current fork PRs/branches first; another agent may have completed an item after this snapshot.
3. Reproduce the reported behavior before fixing it. Hardware-only items remain blocked until the named device/transport is available.
4. Keep each PR focused on one execution item and link both this issue and the upstream report.
5. State exact RN, Expo, architecture, platform, device/ABI, Epson SDK, printer model, and transport in verification evidence.
6. Update this checklist immediately when a PR lands; record deviations and new evidence in a comment rather than silently changing scope.