@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 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 `serialport` depend on the app's authorizations and arrive shortly after load.
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
 
@@ -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);
@@ -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
@@ -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.59.0";
1
+ export declare const apiVersion = "1.60.0";
package/dist/Version.js CHANGED
@@ -1,2 +1,2 @@
1
- export const apiVersion = '1.59.0';
1
+ export const apiVersion = '1.60.0';
2
2
  //# sourceMappingURL=Version.js.map
@@ -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.59.0'"]}
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'"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lavitre/apps",
3
- "version": "1.59.0",
3
+ "version": "1.60.0",
4
4
  "description": "TypeScript SDK for building la Vitre apps (connector, frames, companion, CRDT sync)",
5
5
  "license": "MIT",
6
6
  "type": "module",