@lavitre/apps 1.59.0 → 1.60.0
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.
- package/README.md +23 -2
- package/dist/Native/index.d.ts +86 -0
- package/dist/Native/index.js +77 -0
- package/dist/Native/index.js.map +1 -1
- package/dist/Version.d.ts +1 -1
- package/dist/Version.js +1 -1
- package/dist/Version.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -160,18 +160,39 @@ preview.dispose()
|
|
|
160
160
|
|
|
161
161
|
It listens through `frame.addDeviceStateListener`, so the app's `onDeviceScalingUpdated` & co. stay its own. While the camera cannot be opened, `preview.error` (also in `addListener`'s state) says why — `NotAllowedError`, `NotFoundError`, `TimeoutError`… — and retries continue with a growing delay. `getScaledStream` redraws each frame in a worker on Chromium (insertable streams), on the main thread when the worker cannot run (CSP without `blob:` in `worker-src`), and with a canvas elsewhere. Apps drawing the preview themselves use the pure helpers from `@lavitre/apps/Common`: `resolvePreviewScaling(hostInformation)` → `computePreviewLayout(scaling)` → `previewMatrix(layout, srcW, srcH, outW, outH)`, a matrix for `ctx.setTransform` or CSS `matrix()`.
|
|
162
162
|
|
|
163
|
+
### NFC tags — `watchNfcTags` (SDK 1.60)
|
|
164
|
+
|
|
165
|
+
On a native Vitre with a USB NFC reader (any PC/SC contactless reader: ACS ACR122U / ACR1252U, Identiv, HID Omnikey…), an app holding the `nfc` authorization in its manifest is told when a badge or tag is put down and lifted.
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
import { watchNfcTags } from '@lavitre/apps/Native'
|
|
169
|
+
|
|
170
|
+
const stop = watchNfcTags(
|
|
171
|
+
(e) => {
|
|
172
|
+
if (e.type === 'tagPresent') console.log('badge', e.uid, 'on', e.reader) // uid: upper-case hex, e.g. "AD9B6846"
|
|
173
|
+
if (e.type === 'tagRemoved') console.log('lifted from', e.reader)
|
|
174
|
+
},
|
|
175
|
+
{
|
|
176
|
+
reader: (name) => name.includes('PICC'), // optional: by PC/SC reader name
|
|
177
|
+
onUnavailable: () => console.log('no NFC here'), // web/PWA, companion, no `nfc` authorization, Vitre older than 26.11
|
|
178
|
+
},
|
|
179
|
+
)
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
It waits for `laVitreNative.nfc` (the host adds it shortly after load), reports a tag already on a reader as `tagPresent`, and drops a repeated `tagPresent` for the same tag. Events also include `readerAdded` / `readerRemoved`. Read-only: the UID and the ATR (the tag type), never a channel to send commands to the card; contact smart cards and virtual ones (Windows Hello) are not reported. `laVitreNative.nfc` (`getReaders`, `addTagHandler`, `removeTagHandler`) is there for apps that want the raw bridge. There is no NFC on web/PWA or the companion: no browser API reaches these readers.
|
|
183
|
+
|
|
163
184
|
### Native or web host — `isNativeHost`
|
|
164
185
|
|
|
165
186
|
```ts
|
|
166
187
|
import { getHostEnvironment, isNativeHost, laVitreNative } from '@lavitre/apps/Native'
|
|
167
188
|
|
|
168
189
|
if (isNativeHost()) {
|
|
169
|
-
// desktop Vitre: laVitreNative is there; its io / serialport only with the matching authorization
|
|
190
|
+
// desktop Vitre: laVitreNative is there; its io / serialport / nfc only with the matching authorization
|
|
170
191
|
}
|
|
171
192
|
getHostEnvironment() // 'native' | 'web'
|
|
172
193
|
```
|
|
173
194
|
|
|
174
|
-
The native Vitre injects `window.laVitreNative` into every app frame before any script runs, whatever the manifest; a Vitre in a browser or PWA and the companion leave it unset (`laVitreNative` is then `null`). Feature-detect the members you use: `io` and `
|
|
195
|
+
The native Vitre injects `window.laVitreNative` into every app frame before any script runs, whatever the manifest; a Vitre in a browser or PWA and the companion leave it unset (`laVitreNative` is then `null`). Feature-detect the members you use: `io`, `serialport` and `nfc` depend on the app's authorizations and arrive shortly after load.
|
|
175
196
|
|
|
176
197
|
### AppSettings API — `getSettings` / `setSettings` (three levels)
|
|
177
198
|
|
package/dist/Native/index.d.ts
CHANGED
|
@@ -137,6 +137,53 @@ export type SerialPortInfo = {
|
|
|
137
137
|
export type SerialPortBridge = {
|
|
138
138
|
getSerialPortsWithDescription: () => SerialPortInfo[];
|
|
139
139
|
};
|
|
140
|
+
/** A tag on an NFC reader. Both values are upper-case hex, no separator. */
|
|
141
|
+
export type NfcTag = {
|
|
142
|
+
/**
|
|
143
|
+
* The tag's UID (4, 7 or 10 bytes: `"AD9B6846"`), or `null` when the reader
|
|
144
|
+
* would not give it.
|
|
145
|
+
*/
|
|
146
|
+
uid: string | null;
|
|
147
|
+
/** The ATR the reader built for the tag (identifies its type: MIFARE, NTAG, DESFire…). */
|
|
148
|
+
atr: string;
|
|
149
|
+
};
|
|
150
|
+
/** A PC/SC reader as listed by `nfc.getReaders()`. */
|
|
151
|
+
export type NfcReader = {
|
|
152
|
+
/** PC/SC reader name, e.g. `"ACS ACR122U PICC Interface 0"`. */
|
|
153
|
+
name: string;
|
|
154
|
+
/** The tag on it right now, `null` if none. */
|
|
155
|
+
tag: NfcTag | null;
|
|
156
|
+
};
|
|
157
|
+
/** What `nfc.addTagHandler` reports. */
|
|
158
|
+
export type NfcEvent = ({
|
|
159
|
+
type: 'tagPresent';
|
|
160
|
+
reader: string;
|
|
161
|
+
} & NfcTag) | {
|
|
162
|
+
type: 'tagRemoved' | 'readerAdded' | 'readerRemoved';
|
|
163
|
+
reader: string;
|
|
164
|
+
};
|
|
165
|
+
/**
|
|
166
|
+
* NFC bridge exposed to apps at `window.laVitreNative.nfc` (added in the native
|
|
167
|
+
* Vitre 26.11). It reports badges and tags put on a USB NFC reader (any PC/SC
|
|
168
|
+
* contactless reader: ACS ACR122U / ACR1252U, Identiv, HID Omnikey…).
|
|
169
|
+
*
|
|
170
|
+
* ⚠️ **Conditioned on the app manifest.** Injected **only** when the app
|
|
171
|
+
* declares the `nfc` authorization, and only on a native (Windows) Vitre: no
|
|
172
|
+
* browser API reaches these readers, so there is none on web/PWA or the
|
|
173
|
+
* companion. It arrives shortly after load (an authorization round trip):
|
|
174
|
+
* prefer {@link watchNfcTags}, which waits for it.
|
|
175
|
+
*
|
|
176
|
+
* Read-only: the UID and the ATR, never a channel to send commands to the
|
|
177
|
+
* card. Contact smart cards and virtual ones (Windows Hello) are not reported.
|
|
178
|
+
* Every reader of the machine is listed; pick yours by name if there are
|
|
179
|
+
* several.
|
|
180
|
+
*/
|
|
181
|
+
export type NfcBridge = {
|
|
182
|
+
getReaders: () => NfcReader[];
|
|
183
|
+
/** Returns an id for {@link NfcBridge.removeTagHandler}. */
|
|
184
|
+
addTagHandler: (handler: (event: NfcEvent) => void) => string;
|
|
185
|
+
removeTagHandler: (id: string) => void;
|
|
186
|
+
};
|
|
140
187
|
export type LaVitreNative = {
|
|
141
188
|
process: Process;
|
|
142
189
|
/**
|
|
@@ -152,6 +199,12 @@ export type LaVitreNative = {
|
|
|
152
199
|
* Feature-detect before calling. See {@link SerialPortBridge}.
|
|
153
200
|
*/
|
|
154
201
|
serialport?: SerialPortBridge;
|
|
202
|
+
/**
|
|
203
|
+
* NFC tags on a USB reader. Present **only** when the app holds the `nfc`
|
|
204
|
+
* authorization, on a native Vitre 26.11 or later — otherwise `undefined`.
|
|
205
|
+
* See {@link NfcBridge} and {@link watchNfcTags}.
|
|
206
|
+
*/
|
|
207
|
+
nfc?: NfcBridge;
|
|
155
208
|
};
|
|
156
209
|
/** The native bridge, `null` off a native Vitre (the host leaves the property unset). */
|
|
157
210
|
export declare const laVitreNative: LaVitreNative | null;
|
|
@@ -184,3 +237,36 @@ export declare const getLocalAppStorageUrl: (appId: string, relativePath: string
|
|
|
184
237
|
* ```
|
|
185
238
|
*/
|
|
186
239
|
export declare const downloadFileToAppStorage: (io: IO, args: DownloadFileArgs) => Promise<number>;
|
|
240
|
+
export type WatchNfcTagsOptions = {
|
|
241
|
+
/** Keep only the readers this accepts (by PC/SC name). Default: every reader. */
|
|
242
|
+
reader?: (name: string) => boolean;
|
|
243
|
+
/**
|
|
244
|
+
* How long to wait for `laVitreNative.nfc`, which the host adds shortly after
|
|
245
|
+
* load. Default 10 000 ms.
|
|
246
|
+
*/
|
|
247
|
+
waitMs?: number;
|
|
248
|
+
/**
|
|
249
|
+
* Called once when the bridge never showed up: not a native Vitre, no `nfc`
|
|
250
|
+
* authorization in the manifest, or a Vitre older than 26.11.
|
|
251
|
+
*/
|
|
252
|
+
onUnavailable?: () => void;
|
|
253
|
+
};
|
|
254
|
+
/**
|
|
255
|
+
* Follow the tags put on and lifted from the NFC readers. Added 1.60.
|
|
256
|
+
*
|
|
257
|
+
* - Waits for `laVitreNative.nfc` (see {@link WatchNfcTagsOptions.waitMs}).
|
|
258
|
+
* - A tag already on a reader when watching starts is reported as `tagPresent`.
|
|
259
|
+
* - A `tagPresent` repeated for a tag already reported is dropped.
|
|
260
|
+
*
|
|
261
|
+
* ```ts
|
|
262
|
+
* import { watchNfcTags } from '@lavitre/apps/Native'
|
|
263
|
+
* const stop = watchNfcTags(
|
|
264
|
+
* (e) => { if (e.type === 'tagPresent') console.log('badge', e.uid) },
|
|
265
|
+
* { onUnavailable: () => console.log('no NFC on this Vitre') },
|
|
266
|
+
* )
|
|
267
|
+
* // later: stop()
|
|
268
|
+
* ```
|
|
269
|
+
*
|
|
270
|
+
* Returns a function that stops watching (and stops waiting).
|
|
271
|
+
*/
|
|
272
|
+
export declare const watchNfcTags: (handler: (event: NfcEvent) => void, options?: WatchNfcTagsOptions) => (() => void);
|
package/dist/Native/index.js
CHANGED
|
@@ -21,4 +21,81 @@ export const getLocalAppStorageUrl = (appId, relativePath) => `https://${appId}.
|
|
|
21
21
|
* ```
|
|
22
22
|
*/
|
|
23
23
|
export const downloadFileToAppStorage = (io, args) => new Promise((resolve, reject) => io.downloadFile(args, (error, bytesWritten) => error ? reject(new Error(error)) : resolve(bytesWritten ?? 0)));
|
|
24
|
+
const nfcBridgeNow = () => typeof window === 'undefined'
|
|
25
|
+
? undefined
|
|
26
|
+
: (window.laVitreNative?.nfc ?? undefined);
|
|
27
|
+
/**
|
|
28
|
+
* Follow the tags put on and lifted from the NFC readers. Added 1.60.
|
|
29
|
+
*
|
|
30
|
+
* - Waits for `laVitreNative.nfc` (see {@link WatchNfcTagsOptions.waitMs}).
|
|
31
|
+
* - A tag already on a reader when watching starts is reported as `tagPresent`.
|
|
32
|
+
* - A `tagPresent` repeated for a tag already reported is dropped.
|
|
33
|
+
*
|
|
34
|
+
* ```ts
|
|
35
|
+
* import { watchNfcTags } from '@lavitre/apps/Native'
|
|
36
|
+
* const stop = watchNfcTags(
|
|
37
|
+
* (e) => { if (e.type === 'tagPresent') console.log('badge', e.uid) },
|
|
38
|
+
* { onUnavailable: () => console.log('no NFC on this Vitre') },
|
|
39
|
+
* )
|
|
40
|
+
* // later: stop()
|
|
41
|
+
* ```
|
|
42
|
+
*
|
|
43
|
+
* Returns a function that stops watching (and stops waiting).
|
|
44
|
+
*/
|
|
45
|
+
export const watchNfcTags = (handler, options = {}) => {
|
|
46
|
+
const accepts = options.reader ?? (() => true);
|
|
47
|
+
const waitMs = options.waitMs ?? 10000;
|
|
48
|
+
const tagOn = new Map(); // reader → uid of the tag reported on it
|
|
49
|
+
let stopped = false;
|
|
50
|
+
let detach;
|
|
51
|
+
let timer;
|
|
52
|
+
const deliver = (event) => {
|
|
53
|
+
if (stopped || !accepts(event.reader))
|
|
54
|
+
return;
|
|
55
|
+
if (event.type === 'tagPresent') {
|
|
56
|
+
if (tagOn.has(event.reader) && tagOn.get(event.reader) === event.uid)
|
|
57
|
+
return;
|
|
58
|
+
tagOn.set(event.reader, event.uid);
|
|
59
|
+
}
|
|
60
|
+
else if (event.type === 'tagRemoved' || event.type === 'readerRemoved') {
|
|
61
|
+
if (event.type === 'tagRemoved' && !tagOn.has(event.reader))
|
|
62
|
+
return;
|
|
63
|
+
tagOn.delete(event.reader);
|
|
64
|
+
}
|
|
65
|
+
handler(event);
|
|
66
|
+
};
|
|
67
|
+
const attach = (nfc) => {
|
|
68
|
+
// Handler first: the replay below cannot miss an arrival in between, and
|
|
69
|
+
// `deliver` drops the duplicate if both see the same tag.
|
|
70
|
+
const id = nfc.addTagHandler(deliver);
|
|
71
|
+
detach = () => nfc.removeTagHandler(id);
|
|
72
|
+
for (const reader of nfc.getReaders()) {
|
|
73
|
+
if (reader.tag)
|
|
74
|
+
deliver({ type: 'tagPresent', reader: reader.name, ...reader.tag });
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
const startedAt = Date.now();
|
|
78
|
+
const poll = () => {
|
|
79
|
+
if (stopped)
|
|
80
|
+
return;
|
|
81
|
+
const nfc = nfcBridgeNow();
|
|
82
|
+
if (nfc) {
|
|
83
|
+
attach(nfc);
|
|
84
|
+
}
|
|
85
|
+
else if (Date.now() - startedAt >= waitMs) {
|
|
86
|
+
options.onUnavailable?.();
|
|
87
|
+
}
|
|
88
|
+
else {
|
|
89
|
+
timer = setTimeout(poll, 200);
|
|
90
|
+
}
|
|
91
|
+
};
|
|
92
|
+
poll();
|
|
93
|
+
return () => {
|
|
94
|
+
stopped = true;
|
|
95
|
+
if (timer !== undefined)
|
|
96
|
+
clearTimeout(timer);
|
|
97
|
+
detach?.();
|
|
98
|
+
detach = undefined;
|
|
99
|
+
};
|
|
100
|
+
};
|
|
24
101
|
//# sourceMappingURL=index.js.map
|
package/dist/Native/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../Native/index.ts"],"names":[],"mappings":"AA0KA,yFAAyF;AACzF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAE,MAAc,CAAC,aAAa;IACzD,IAAI,CAAyB,CAAA;AAY/B,wFAAwF;AACxF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAY,EAAE,CACxC,OAAO,MAAM,KAAK,WAAW,IAAK,MAAc,CAAC,aAAa,IAAI,IAAI,CAAA;AAExE,4GAA4G;AAC5G,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAoB,EAAE,CACtD,YAAY,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAA;AAEnC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAa,EAAE,YAAoB,EAAE,EAAE,CAC3E,WAAW,KAAK,uBAAuB,YAAY,EAAE,CAAA;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,EAAM,EACN,IAAsB,EACL,EAAE,CACnB,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CACtC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,CAC5C,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC,CAC9D,CACF,CAAA","sourcesContent":["export type StartProcessArgs = {\n path: string\n args: string[]\n ignoreFormatPath?: boolean\n hidden?: boolean\n}\n\nexport type Capture = {\n startCapture: (options: {\n outputFile: string\n audioInput: string\n }) => Promise<void>\n stopCurrentCapture: () => void\n}\n\nexport type ReadBinaryArgs = {\n path: string\n bufferSize?: number\n position?: number\n}\n\nexport type BinaryChunkResult = {\n buffer: ArrayBufferLike\n read: number\n fileSize: number\n position: number\n}\n\nexport type DownloadProgress = {\n /** Bytes written to disk so far. */\n received: number\n /** Total bytes, when the server advertises a `Content-Length`. */\n total?: number\n}\n\nexport type DownloadFileArgs = {\n /** Source URL to fetch. */\n url: string\n /**\n * Destination path inside the app sandbox (e.g. `~/media/cover.png`). The\n * native bridge resolves it through the app path formatter, so it is scoped\n * to `<vitre-data>/apps/<appId>/...` — it cannot escape the app storage.\n */\n path: string\n /** Optional extra request headers. */\n headers?: Record<string, string>\n /** Optional progress callback fired as bytes are streamed to disk. */\n progress?: (progress: DownloadProgress) => void\n}\n\nexport type FileInfoType = 'file' | 'directory'\n\nexport type FileInfo = {\n name: string\n path: string\n type: FileInfoType\n}\nexport type Process = {\n startProcess: (args: StartProcessArgs) => void\n}\n\n/**\n * Native file I/O for the app, exposed at `window.laVitreNative.io`.\n *\n * ⚠️ **Conditioned on the app manifest.** This bridge is injected **only** when\n * the app declares a storage authorization:\n * - **`appsStorage`** — paths are confined to the app's own storage folder\n * (absolute paths, the `~~/` parent escape and `../` traversal are rejected).\n * This is what most apps want.\n * - **`fullStorage`** — unrestricted filesystem access. Use only when strictly\n * necessary.\n *\n * With neither authorization, `laVitreNative.io` is `undefined` — always\n * feature-detect (`laVitreNative?.io`) before use. It is also `undefined` off a\n * native Vitre (`laVitreNative` itself is `null` on web/PWA and the companion,\n * see {@link isNativeHost}). The host adds it shortly after the page starts\n * (an authorization round trip), so a check at load time can miss it.\n *\n * Paths use a `~/` prefix for the app's sandbox root, e.g. `~/data/x.json`; the\n * file written there is served by the Vitre's local web server at\n * {@link getLocalAppStorageUrl}`(appId, 'data/x.json')`.\n */\nexport type IO = {\n readFile: (path: string) => string\n /** True if a file exists at `path` (resolved inside the app sandbox). */\n fileExists: (path: string) => boolean\n /**\n * Write a file to the app sandbox.\n *\n * - Pass a `string` for text content (written as UTF-8).\n * - Pass an `ArrayBuffer` (or any `ArrayBufferLike`) for binary content — the\n * raw bytes are written as-is. Do **not** base64-encode binary data. For a\n * typed array, pass its `.buffer` (e.g. `new Uint8Array(...).buffer`, or\n * `await blob.arrayBuffer()`).\n */\n writeFile: (path: string, content: string | ArrayBufferLike) => void\n list: (path: string) => FileInfo[]\n createFolder: (path: string) => void\n formatPath: (path: string) => string\n deleteFile: (path: string) => void\n readBinaryFileBuffer: (args: ReadBinaryArgs) => Promise<BinaryChunkResult>\n /**\n * Download a URL straight into a file in the app sandbox. Binary-safe: the\n * response body is streamed to disk natively, so nothing is buffered in JS\n * (ideal for large media). Node-style callback `(error, bytesWritten)`.\n *\n * Prefer {@link downloadFileToAppStorage} for a promise-based API.\n */\n downloadFile: (\n args: DownloadFileArgs,\n callback: (error: string | null, bytesWritten: number | null) => void,\n ) => void\n}\n\n/** A serial port as enumerated by `serialport.getSerialPortsWithDescription()`. */\nexport type SerialPortInfo = {\n /** OS port name, e.g. `\"COM3\"`. */\n port: string\n /** Human-readable device caption reported by the OS. */\n description: string\n /**\n * USB vendor id (decimal), or `null` for non-USB ports (e.g. a built-in\n * motherboard serial). Same shape as `navigator.serial` `getInfo()`, so it\n * can be matched against `requestSerialPortAccess` / `requestPort` filters.\n */\n usbVendorId: number | null\n /** USB product id (decimal), or `null` for non-USB ports. */\n usbProductId: number | null\n}\n\n/**\n * Serial-port bridge exposed to apps at `window.laVitreNative.serialport`.\n *\n * ⚠️ **Conditioned on the app manifest.** This bridge is injected **only** when\n * the app declares the `webSerial` authorization in its manifest. For apps it\n * is intentionally read-only: it exposes **only** `getSerialPortsWithDescription`\n * (port enumeration). Opening / reading / writing a port is done through the\n * standard `navigator.serial` Web Serial API (gated by the same authorization),\n * not through this bridge.\n *\n * Always feature-detect before use — the whole object is `undefined` when the\n * app is not authorized:\n *\n * ```ts\n * const sp = laVitreNative?.serialport\n * if (!sp) return // app lacks the `webSerial` authorization\n * const ports = sp.getSerialPortsWithDescription()\n * ```\n */\nexport type SerialPortBridge = {\n getSerialPortsWithDescription: () => SerialPortInfo[]\n}\n\nexport type LaVitreNative = {\n process: Process\n /**\n * File I/O. Present **only** when the app holds the `appsStorage` (sandboxed)\n * or `fullStorage` (unrestricted) authorization — otherwise `undefined`.\n * Feature-detect before calling. See {@link IO}.\n */\n io?: IO\n capture: Capture\n /**\n * Serial-port enumeration. Present **only** when the app holds the\n * `webSerial` authorization in its manifest — otherwise `undefined`.\n * Feature-detect before calling. See {@link SerialPortBridge}.\n */\n serialport?: SerialPortBridge\n}\n\n/** The native bridge, `null` off a native Vitre (the host leaves the property unset). */\nexport const laVitreNative = ((window as any).laVitreNative ??\n null) as LaVitreNative | null\n\n/**\n * Where the app runs:\n * - `native`: the desktop Vitre (CEF shell). It injects `window.laVitreNative`\n * into every app frame before any script runs, whatever the app manifest —\n * only its members depend on the platform and on the authorizations.\n * - `web`: a Vitre in a browser or installed as a PWA, the companion, or any\n * page outside la Vitre. No native bridge.\n */\nexport type HostEnvironment = 'native' | 'web'\n\n/** True on a native (desktop) Vitre, where `laVitreNative` is available. Added 1.53. */\nexport const isNativeHost = (): boolean =>\n typeof window !== 'undefined' && (window as any).laVitreNative != null\n\n/** `native` on a native (desktop) Vitre, `web` everywhere else. See {@link HostEnvironment}. Added 1.53. */\nexport const getHostEnvironment = (): HostEnvironment =>\n isNativeHost() ? 'native' : 'web'\n\nexport const getLocalAppStorageUrl = (appId: string, relativePath: string) =>\n `https://${appId}.local.app.lavit.re/${relativePath}`\n\n/**\n * Promise wrapper around {@link IO.downloadFile}. Resolves to the number of\n * bytes written, rejects with the native error.\n *\n * ```ts\n * import { laVitreNative, downloadFileToAppStorage } from '@lavitre/apps/Native'\n * if (laVitreNative)\n * await downloadFileToAppStorage(laVitreNative.io, {\n * url: 'https://storage.lavit.re/apps/my-app/cover.png',\n * path: '~/media/cover.png',\n * progress: ({ received, total }) => console.log(received, total),\n * })\n * ```\n */\nexport const downloadFileToAppStorage = (\n io: IO,\n args: DownloadFileArgs,\n): Promise<number> =>\n new Promise<number>((resolve, reject) =>\n io.downloadFile(args, (error, bytesWritten) =>\n error ? reject(new Error(error)) : resolve(bytesWritten ?? 0),\n ),\n )\n"]}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../Native/index.ts"],"names":[],"mappings":"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","sourcesContent":["export type StartProcessArgs = {\n path: string\n args: string[]\n ignoreFormatPath?: boolean\n hidden?: boolean\n}\n\nexport type Capture = {\n startCapture: (options: {\n outputFile: string\n audioInput: string\n }) => Promise<void>\n stopCurrentCapture: () => void\n}\n\nexport type ReadBinaryArgs = {\n path: string\n bufferSize?: number\n position?: number\n}\n\nexport type BinaryChunkResult = {\n buffer: ArrayBufferLike\n read: number\n fileSize: number\n position: number\n}\n\nexport type DownloadProgress = {\n /** Bytes written to disk so far. */\n received: number\n /** Total bytes, when the server advertises a `Content-Length`. */\n total?: number\n}\n\nexport type DownloadFileArgs = {\n /** Source URL to fetch. */\n url: string\n /**\n * Destination path inside the app sandbox (e.g. `~/media/cover.png`). The\n * native bridge resolves it through the app path formatter, so it is scoped\n * to `<vitre-data>/apps/<appId>/...` — it cannot escape the app storage.\n */\n path: string\n /** Optional extra request headers. */\n headers?: Record<string, string>\n /** Optional progress callback fired as bytes are streamed to disk. */\n progress?: (progress: DownloadProgress) => void\n}\n\nexport type FileInfoType = 'file' | 'directory'\n\nexport type FileInfo = {\n name: string\n path: string\n type: FileInfoType\n}\nexport type Process = {\n startProcess: (args: StartProcessArgs) => void\n}\n\n/**\n * Native file I/O for the app, exposed at `window.laVitreNative.io`.\n *\n * ⚠️ **Conditioned on the app manifest.** This bridge is injected **only** when\n * the app declares a storage authorization:\n * - **`appsStorage`** — paths are confined to the app's own storage folder\n * (absolute paths, the `~~/` parent escape and `../` traversal are rejected).\n * This is what most apps want.\n * - **`fullStorage`** — unrestricted filesystem access. Use only when strictly\n * necessary.\n *\n * With neither authorization, `laVitreNative.io` is `undefined` — always\n * feature-detect (`laVitreNative?.io`) before use. It is also `undefined` off a\n * native Vitre (`laVitreNative` itself is `null` on web/PWA and the companion,\n * see {@link isNativeHost}). The host adds it shortly after the page starts\n * (an authorization round trip), so a check at load time can miss it.\n *\n * Paths use a `~/` prefix for the app's sandbox root, e.g. `~/data/x.json`; the\n * file written there is served by the Vitre's local web server at\n * {@link getLocalAppStorageUrl}`(appId, 'data/x.json')`.\n */\nexport type IO = {\n readFile: (path: string) => string\n /** True if a file exists at `path` (resolved inside the app sandbox). */\n fileExists: (path: string) => boolean\n /**\n * Write a file to the app sandbox.\n *\n * - Pass a `string` for text content (written as UTF-8).\n * - Pass an `ArrayBuffer` (or any `ArrayBufferLike`) for binary content — the\n * raw bytes are written as-is. Do **not** base64-encode binary data. For a\n * typed array, pass its `.buffer` (e.g. `new Uint8Array(...).buffer`, or\n * `await blob.arrayBuffer()`).\n */\n writeFile: (path: string, content: string | ArrayBufferLike) => void\n list: (path: string) => FileInfo[]\n createFolder: (path: string) => void\n formatPath: (path: string) => string\n deleteFile: (path: string) => void\n readBinaryFileBuffer: (args: ReadBinaryArgs) => Promise<BinaryChunkResult>\n /**\n * Download a URL straight into a file in the app sandbox. Binary-safe: the\n * response body is streamed to disk natively, so nothing is buffered in JS\n * (ideal for large media). Node-style callback `(error, bytesWritten)`.\n *\n * Prefer {@link downloadFileToAppStorage} for a promise-based API.\n */\n downloadFile: (\n args: DownloadFileArgs,\n callback: (error: string | null, bytesWritten: number | null) => void,\n ) => void\n}\n\n/** A serial port as enumerated by `serialport.getSerialPortsWithDescription()`. */\nexport type SerialPortInfo = {\n /** OS port name, e.g. `\"COM3\"`. */\n port: string\n /** Human-readable device caption reported by the OS. */\n description: string\n /**\n * USB vendor id (decimal), or `null` for non-USB ports (e.g. a built-in\n * motherboard serial). Same shape as `navigator.serial` `getInfo()`, so it\n * can be matched against `requestSerialPortAccess` / `requestPort` filters.\n */\n usbVendorId: number | null\n /** USB product id (decimal), or `null` for non-USB ports. */\n usbProductId: number | null\n}\n\n/**\n * Serial-port bridge exposed to apps at `window.laVitreNative.serialport`.\n *\n * ⚠️ **Conditioned on the app manifest.** This bridge is injected **only** when\n * the app declares the `webSerial` authorization in its manifest. For apps it\n * is intentionally read-only: it exposes **only** `getSerialPortsWithDescription`\n * (port enumeration). Opening / reading / writing a port is done through the\n * standard `navigator.serial` Web Serial API (gated by the same authorization),\n * not through this bridge.\n *\n * Always feature-detect before use — the whole object is `undefined` when the\n * app is not authorized:\n *\n * ```ts\n * const sp = laVitreNative?.serialport\n * if (!sp) return // app lacks the `webSerial` authorization\n * const ports = sp.getSerialPortsWithDescription()\n * ```\n */\nexport type SerialPortBridge = {\n getSerialPortsWithDescription: () => SerialPortInfo[]\n}\n\n/** A tag on an NFC reader. Both values are upper-case hex, no separator. */\nexport type NfcTag = {\n /**\n * The tag's UID (4, 7 or 10 bytes: `\"AD9B6846\"`), or `null` when the reader\n * would not give it.\n */\n uid: string | null\n /** The ATR the reader built for the tag (identifies its type: MIFARE, NTAG, DESFire…). */\n atr: string\n}\n\n/** A PC/SC reader as listed by `nfc.getReaders()`. */\nexport type NfcReader = {\n /** PC/SC reader name, e.g. `\"ACS ACR122U PICC Interface 0\"`. */\n name: string\n /** The tag on it right now, `null` if none. */\n tag: NfcTag | null\n}\n\n/** What `nfc.addTagHandler` reports. */\nexport type NfcEvent =\n | ({ type: 'tagPresent'; reader: string } & NfcTag)\n | { type: 'tagRemoved' | 'readerAdded' | 'readerRemoved'; reader: string }\n\n/**\n * NFC bridge exposed to apps at `window.laVitreNative.nfc` (added in the native\n * Vitre 26.11). It reports badges and tags put on a USB NFC reader (any PC/SC\n * contactless reader: ACS ACR122U / ACR1252U, Identiv, HID Omnikey…).\n *\n * ⚠️ **Conditioned on the app manifest.** Injected **only** when the app\n * declares the `nfc` authorization, and only on a native (Windows) Vitre: no\n * browser API reaches these readers, so there is none on web/PWA or the\n * companion. It arrives shortly after load (an authorization round trip):\n * prefer {@link watchNfcTags}, which waits for it.\n *\n * Read-only: the UID and the ATR, never a channel to send commands to the\n * card. Contact smart cards and virtual ones (Windows Hello) are not reported.\n * Every reader of the machine is listed; pick yours by name if there are\n * several.\n */\nexport type NfcBridge = {\n getReaders: () => NfcReader[]\n /** Returns an id for {@link NfcBridge.removeTagHandler}. */\n addTagHandler: (handler: (event: NfcEvent) => void) => string\n removeTagHandler: (id: string) => void\n}\n\nexport type LaVitreNative = {\n process: Process\n /**\n * File I/O. Present **only** when the app holds the `appsStorage` (sandboxed)\n * or `fullStorage` (unrestricted) authorization — otherwise `undefined`.\n * Feature-detect before calling. See {@link IO}.\n */\n io?: IO\n capture: Capture\n /**\n * Serial-port enumeration. Present **only** when the app holds the\n * `webSerial` authorization in its manifest — otherwise `undefined`.\n * Feature-detect before calling. See {@link SerialPortBridge}.\n */\n serialport?: SerialPortBridge\n /**\n * NFC tags on a USB reader. Present **only** when the app holds the `nfc`\n * authorization, on a native Vitre 26.11 or later — otherwise `undefined`.\n * See {@link NfcBridge} and {@link watchNfcTags}.\n */\n nfc?: NfcBridge\n}\n\n/** The native bridge, `null` off a native Vitre (the host leaves the property unset). */\nexport const laVitreNative = ((window as any).laVitreNative ??\n null) as LaVitreNative | null\n\n/**\n * Where the app runs:\n * - `native`: the desktop Vitre (CEF shell). It injects `window.laVitreNative`\n * into every app frame before any script runs, whatever the app manifest —\n * only its members depend on the platform and on the authorizations.\n * - `web`: a Vitre in a browser or installed as a PWA, the companion, or any\n * page outside la Vitre. No native bridge.\n */\nexport type HostEnvironment = 'native' | 'web'\n\n/** True on a native (desktop) Vitre, where `laVitreNative` is available. Added 1.53. */\nexport const isNativeHost = (): boolean =>\n typeof window !== 'undefined' && (window as any).laVitreNative != null\n\n/** `native` on a native (desktop) Vitre, `web` everywhere else. See {@link HostEnvironment}. Added 1.53. */\nexport const getHostEnvironment = (): HostEnvironment =>\n isNativeHost() ? 'native' : 'web'\n\nexport const getLocalAppStorageUrl = (appId: string, relativePath: string) =>\n `https://${appId}.local.app.lavit.re/${relativePath}`\n\n/**\n * Promise wrapper around {@link IO.downloadFile}. Resolves to the number of\n * bytes written, rejects with the native error.\n *\n * ```ts\n * import { laVitreNative, downloadFileToAppStorage } from '@lavitre/apps/Native'\n * if (laVitreNative)\n * await downloadFileToAppStorage(laVitreNative.io, {\n * url: 'https://storage.lavit.re/apps/my-app/cover.png',\n * path: '~/media/cover.png',\n * progress: ({ received, total }) => console.log(received, total),\n * })\n * ```\n */\nexport const downloadFileToAppStorage = (\n io: IO,\n args: DownloadFileArgs,\n): Promise<number> =>\n new Promise<number>((resolve, reject) =>\n io.downloadFile(args, (error, bytesWritten) =>\n error ? reject(new Error(error)) : resolve(bytesWritten ?? 0),\n ),\n )\n\nexport type WatchNfcTagsOptions = {\n /** Keep only the readers this accepts (by PC/SC name). Default: every reader. */\n reader?: (name: string) => boolean\n /**\n * How long to wait for `laVitreNative.nfc`, which the host adds shortly after\n * load. Default 10 000 ms.\n */\n waitMs?: number\n /**\n * Called once when the bridge never showed up: not a native Vitre, no `nfc`\n * authorization in the manifest, or a Vitre older than 26.11.\n */\n onUnavailable?: () => void\n}\n\nconst nfcBridgeNow = (): NfcBridge | undefined =>\n typeof window === 'undefined'\n ? undefined\n : ((window as any).laVitreNative?.nfc ?? undefined)\n\n/**\n * Follow the tags put on and lifted from the NFC readers. Added 1.60.\n *\n * - Waits for `laVitreNative.nfc` (see {@link WatchNfcTagsOptions.waitMs}).\n * - A tag already on a reader when watching starts is reported as `tagPresent`.\n * - A `tagPresent` repeated for a tag already reported is dropped.\n *\n * ```ts\n * import { watchNfcTags } from '@lavitre/apps/Native'\n * const stop = watchNfcTags(\n * (e) => { if (e.type === 'tagPresent') console.log('badge', e.uid) },\n * { onUnavailable: () => console.log('no NFC on this Vitre') },\n * )\n * // later: stop()\n * ```\n *\n * Returns a function that stops watching (and stops waiting).\n */\nexport const watchNfcTags = (\n handler: (event: NfcEvent) => void,\n options: WatchNfcTagsOptions = {},\n): (() => void) => {\n const accepts = options.reader ?? (() => true)\n const waitMs = options.waitMs ?? 10_000\n const tagOn = new Map<string, string | null>() // reader → uid of the tag reported on it\n let stopped = false\n let detach: (() => void) | undefined\n let timer: ReturnType<typeof setTimeout> | undefined\n\n const deliver = (event: NfcEvent) => {\n if (stopped || !accepts(event.reader)) return\n if (event.type === 'tagPresent') {\n if (tagOn.has(event.reader) && tagOn.get(event.reader) === event.uid)\n return\n tagOn.set(event.reader, event.uid)\n } else if (event.type === 'tagRemoved' || event.type === 'readerRemoved') {\n if (event.type === 'tagRemoved' && !tagOn.has(event.reader)) return\n tagOn.delete(event.reader)\n }\n handler(event)\n }\n\n const attach = (nfc: NfcBridge) => {\n // Handler first: the replay below cannot miss an arrival in between, and\n // `deliver` drops the duplicate if both see the same tag.\n const id = nfc.addTagHandler(deliver)\n detach = () => nfc.removeTagHandler(id)\n for (const reader of nfc.getReaders()) {\n if (reader.tag)\n deliver({ type: 'tagPresent', reader: reader.name, ...reader.tag })\n }\n }\n\n const startedAt = Date.now()\n const poll = () => {\n if (stopped) return\n const nfc = nfcBridgeNow()\n if (nfc) {\n attach(nfc)\n } else if (Date.now() - startedAt >= waitMs) {\n options.onUnavailable?.()\n } else {\n timer = setTimeout(poll, 200)\n }\n }\n poll()\n\n return () => {\n stopped = true\n if (timer !== undefined) clearTimeout(timer)\n detach?.()\n detach = undefined\n }\n}\n"]}
|
package/dist/Version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const apiVersion = "1.
|
|
1
|
+
export declare const apiVersion = "1.60.0";
|
package/dist/Version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export const apiVersion = '1.
|
|
1
|
+
export const apiVersion = '1.60.0';
|
|
2
2
|
//# sourceMappingURL=Version.js.map
|
package/dist/Version.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Version.js","sourceRoot":"","sources":["../Version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAA","sourcesContent":["export const apiVersion = '1.
|
|
1
|
+
{"version":3,"file":"Version.js","sourceRoot":"","sources":["../Version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAA","sourcesContent":["export const apiVersion = '1.60.0'"]}
|