@scanfit/browser 0.1.0-alpha.1 → 0.1.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +71 -21
  2. package/package.json +2 -1
package/README.md CHANGED
@@ -1,8 +1,20 @@
1
1
  # @scanfit/browser
2
2
 
3
- Turn camera captures or image files into an inspected PDF that fits a byte limit. Processing stays in the browser; ScanFit does not upload documents or require a backend.
3
+ Build an in-browser document workflow that turns camera captures or image files into an inspected PDF under an exact upload limit.
4
4
 
5
- > Public alpha: test the exported pixels and your target devices before using ScanFit in a production document workflow.
5
+ **Capture or import → detect and correct → reorder → fit the byte limit → inspect → receive a PDF `File`.**
6
+
7
+ - [Try the live demo](https://scanfit-two.vercel.app)
8
+ - [Read the complete documentation](https://github.com/Ahmedsultan09/scanfit#readme)
9
+ - [Report a problem or share feedback](https://github.com/Ahmedsultan09/scanfit/issues)
10
+
11
+ > ScanFit is a public alpha under active development. Test it with the real documents, browsers and physical devices your users have before adopting it in a production workflow.
12
+
13
+ ## Why ScanFit?
14
+
15
+ A document-upload field often assumes the PDF already exists. When the source is still on paper, users may have to leave a form, open a separate scanner app, export a PDF, return to the form and discover that the file exceeds the portal's limit.
16
+
17
+ ScanFit lets the host application provide that workflow without sending the document to a ScanFit backend. The host receives the confirmed `File` and remains responsible for submission.
6
18
 
7
19
  ## Install
8
20
 
@@ -10,7 +22,7 @@ Turn camera captures or image files into an inspected PDF that fits a byte limit
10
22
  npm install @scanfit/browser@next
11
23
  ```
12
24
 
13
- React is an optional peer dependency. Install React 18.2 or 19 when using the ready-made interface.
25
+ React is optional. Install React 18.2 or 19 only when using the ready-made React interface.
14
26
 
15
27
  ## React scanner
16
28
 
@@ -23,7 +35,7 @@ export function ApplicationDocuments() {
23
35
  <DocumentScanner
24
36
  maxBytes={2_000_000}
25
37
  onComplete={({ file, report }) => {
26
- // Called after the user inspects and confirms the exported PDF.
38
+ // Runs after the user inspects and confirms the exported PDF.
27
39
  attachToForm(file, report);
28
40
  }}
29
41
  />
@@ -31,9 +43,9 @@ export function ApplicationDocuments() {
31
43
  }
32
44
  ```
33
45
 
34
- Use `@scanfit/browser/trigger` for a small lazy-loaded dialog launcher, or `useScanSession` for a headless React integration.
46
+ Use `@scanfit/browser/trigger` for a small lazy-loaded dialog launcher or `useScanSession` for a headless React integration.
35
47
 
36
- ## Framework-independent core
48
+ ## Framework-independent TypeScript
37
49
 
38
50
  ```ts
39
51
  import { createScanSession } from "@scanfit/browser/core";
@@ -52,30 +64,68 @@ if (result.status === "ready") {
52
64
  session.dispose();
53
65
  ```
54
66
 
55
- ## What it provides
67
+ ## Computer vision in the browser
68
+
69
+ The built-in classical detector runs locally in the processing worker. It uses luminance preprocessing, connected edges, region candidates and line geometry to estimate the document's four corners. Those corners drive perspective correction so an angled phone photo becomes a flat page.
70
+
71
+ Detection is deliberately treated as fallible:
72
+
73
+ - Low-confidence results fall back to manual cropping.
74
+ - Users can adjust all four corners with pointer, keyboard or tap-operated controls.
75
+ - Advisory warnings identify possibly blurry, dark or low-resolution pages.
76
+ - Detector diagnostics expose confidence, edge support, contrast, coverage and rectangularity.
77
+ - The detector is replaceable through the framework-independent `DocumentDetector` interface.
78
+
79
+ No ML model, document-related network request or public CDN is required by the default workflow.
80
+
81
+ ## Exact finished-PDF size contract
82
+
83
+ `maxBytes` is a required positive integer. ScanFit measures the completed PDF, including structural overhead—not only the JPEG page images.
84
+
85
+ - A `ready` result never exceeds `maxBytes`.
86
+ - Reports include total bytes and each page's image bytes, dimensions, JPEG quality, attempt count, warnings and final compressed preview.
87
+ - The review screen displays the compressed pixels that will be embedded in the PDF.
88
+ - `cannot-fit` is returned when the bounded search cannot meet the limit without crossing the configured quality and resolution floors.
89
+ - ScanFit never silently removes pages, changes the color mode or crosses those floors.
90
+
91
+ Quality floors constrain automatic compression; they do not guarantee that text is readable. Users should inspect small text, signatures, stamps and faint marks before confirmation.
92
+
93
+ ## Included workflow
94
+
95
+ - Manual camera capture and JPEG, PNG or WebP import.
96
+ - Automatic corner detection with manual correction.
97
+ - Perspective correction, rotation, retaking and removal.
98
+ - Drag-free page reordering.
99
+ - Natural color, grayscale and contrast filters.
100
+ - A4, US Letter and image-proportional PDF pages.
101
+ - Worker processing, cancellation, stale-job protection and cleanup.
102
+ - Message dictionaries, RTL layout support and CSS variables.
103
+ - React components plus a framework-independent TypeScript core.
104
+
105
+ ## Package entry points
56
106
 
57
- - JPEG, PNG and WebP import plus manual camera capture.
58
- - Independent document-edge detection with manual corner correction.
59
- - Rotation, natural color, grayscale and contrast adjustments.
60
- - Page removal and reordering with drag-free controls.
61
- - A bounded compression search and exact completed-PDF byte check.
62
- - Per-page byte diagnostics and previews of the compressed pixels embedded in the PDF.
63
- - Worker processing, cancellation, stale-job protection and resource cleanup.
64
- - Replaceable detector and framework-independent TypeScript interfaces.
107
+ | Import | Purpose |
108
+ | --- | --- |
109
+ | `@scanfit/browser/react` | Ready-made scanner and `useScanSession` |
110
+ | `@scanfit/browser/trigger` | Small lazy-loaded scanner trigger |
111
+ | `@scanfit/browser/core` | Sessions, validation, worker coordination and types |
112
+ | `@scanfit/browser/detector` | Replaceable classical detector |
113
+ | `@scanfit/browser/pdf` | Bounded PDF size planner and writer |
114
+ | `@scanfit/browser/styles.css` | Optional ready-made interface styles |
65
115
 
66
- ScanFit returns `cannot-fit` when the configured quality and resolution floors cannot meet the requested limit. It does not silently omit pages, cross those floors, or switch color modes.
116
+ ## Current alpha limits
67
117
 
68
- ## Current limits
118
+ ScanFit currently creates image-only PDFs. It does not include HEIC conversion, existing-PDF import, OCR, searchable or tagged PDFs, redaction, automatic capture, document persistence, telemetry or uploads.
69
119
 
70
- The alpha creates image-only PDFs. It does not include HEIC conversion, existing-PDF import, OCR, searchable or tagged PDFs, redaction, automatic capture, document persistence, telemetry or uploads. Camera behavior and performance still require validation on your supported physical devices.
120
+ Camera behavior, browser codec fallbacks, accessibility and performance still require broader testing on physical mobile devices and real document collections. If you try ScanFit, please report difficult detection cases, unclear controls, output-quality problems, integration friction and missing workflows through [GitHub Issues](https://github.com/Ahmedsultan09/scanfit/issues).
71
121
 
72
- ## Documentation
122
+ ## Documentation and examples
73
123
 
74
124
  - [Complete usage and API guide](https://github.com/Ahmedsultan09/scanfit#readme)
75
- - [Independent detector design](https://github.com/Ahmedsultan09/scanfit/blob/main/docs/DETECTOR.md)
125
+ - [Detector design](https://github.com/Ahmedsultan09/scanfit/blob/main/docs/DETECTOR.md)
76
126
  - [Verification evidence](https://github.com/Ahmedsultan09/scanfit/blob/main/docs/VERIFICATION.md)
77
127
  - [Release checklist](https://github.com/Ahmedsultan09/scanfit/blob/main/docs/RELEASE_CHECKLIST.md)
78
- - [Runnable framework examples](https://github.com/Ahmedsultan09/scanfit/tree/main/examples)
128
+ - [Next.js, React, Vue, Svelte and vanilla TypeScript examples](https://github.com/Ahmedsultan09/scanfit/tree/main/examples)
79
129
  - [Security policy](https://github.com/Ahmedsultan09/scanfit/blob/main/SECURITY.md)
80
130
 
81
131
  MIT licensed. Public reports and fixtures must use synthetic, licensed or fully redacted documents.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scanfit/browser",
3
- "version": "0.1.0-alpha.1",
3
+ "version": "0.1.0-alpha.2",
4
4
  "description": "Local, size-constrained scan-to-PDF workflows for the browser",
5
5
  "keywords": [
6
6
  "document-scanner",
@@ -29,6 +29,7 @@
29
29
  ],
30
30
  "files": [
31
31
  "dist",
32
+ "README.md",
32
33
  "LICENSE",
33
34
  "THIRD_PARTY_NOTICES.md"
34
35
  ],