@lavitre/apps 1.52.0 → 1.53.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 +13 -0
- package/dist/Native/index.d.ts +17 -1
- package/dist/Native/index.js +7 -2
- 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
|
@@ -142,6 +142,19 @@ preview.dispose()
|
|
|
142
142
|
|
|
143
143
|
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()`.
|
|
144
144
|
|
|
145
|
+
### Native or web host — `isNativeHost`
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
import { getHostEnvironment, isNativeHost, laVitreNative } from '@lavitre/apps/Native'
|
|
149
|
+
|
|
150
|
+
if (isNativeHost()) {
|
|
151
|
+
// desktop Vitre: laVitreNative is there; its io / serialport only with the matching authorization
|
|
152
|
+
}
|
|
153
|
+
getHostEnvironment() // 'native' | 'web'
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
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.
|
|
157
|
+
|
|
145
158
|
## Development
|
|
146
159
|
|
|
147
160
|
`pnpm typecheck`, `pnpm build`, and `pnpm test` for the unit tests (`node:test`; Node ≥ 22.18 runs the TypeScript directly).
|
package/dist/Native/index.d.ts
CHANGED
|
@@ -64,7 +64,9 @@ export type Process = {
|
|
|
64
64
|
*
|
|
65
65
|
* With neither authorization, `laVitreNative.io` is `undefined` — always
|
|
66
66
|
* feature-detect (`laVitreNative?.io`) before use. It is also `undefined` off a
|
|
67
|
-
* native Vitre (`laVitreNative` itself is `null` on web/PWA and the companion
|
|
67
|
+
* native Vitre (`laVitreNative` itself is `null` on web/PWA and the companion,
|
|
68
|
+
* see {@link isNativeHost}). The host adds it shortly after the page starts
|
|
69
|
+
* (an authorization round trip), so a check at load time can miss it.
|
|
68
70
|
*
|
|
69
71
|
* Paths use a `~/` prefix for the app's sandbox root, e.g. `~/data/x.json`; the
|
|
70
72
|
* file written there is served by the Vitre's local web server at
|
|
@@ -151,7 +153,21 @@ export type LaVitreNative = {
|
|
|
151
153
|
*/
|
|
152
154
|
serialport?: SerialPortBridge;
|
|
153
155
|
};
|
|
156
|
+
/** The native bridge, `null` off a native Vitre (the host leaves the property unset). */
|
|
154
157
|
export declare const laVitreNative: LaVitreNative | null;
|
|
158
|
+
/**
|
|
159
|
+
* Where the app runs:
|
|
160
|
+
* - `native`: the desktop Vitre (CEF shell). It injects `window.laVitreNative`
|
|
161
|
+
* into every app frame before any script runs, whatever the app manifest —
|
|
162
|
+
* only its members depend on the platform and on the authorizations.
|
|
163
|
+
* - `web`: a Vitre in a browser or installed as a PWA, the companion, or any
|
|
164
|
+
* page outside la Vitre. No native bridge.
|
|
165
|
+
*/
|
|
166
|
+
export type HostEnvironment = 'native' | 'web';
|
|
167
|
+
/** True on a native (desktop) Vitre, where `laVitreNative` is available. Added 1.53. */
|
|
168
|
+
export declare const isNativeHost: () => boolean;
|
|
169
|
+
/** `native` on a native (desktop) Vitre, `web` everywhere else. See {@link HostEnvironment}. Added 1.53. */
|
|
170
|
+
export declare const getHostEnvironment: () => HostEnvironment;
|
|
155
171
|
export declare const getLocalAppStorageUrl: (appId: string, relativePath: string) => string;
|
|
156
172
|
/**
|
|
157
173
|
* Promise wrapper around {@link IO.downloadFile}. Resolves to the number of
|
package/dist/Native/index.js
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/** The native bridge, `null` off a native Vitre (the host leaves the property unset). */
|
|
2
|
+
export const laVitreNative = (window.laVitreNative ??
|
|
3
|
+
null);
|
|
4
|
+
/** True on a native (desktop) Vitre, where `laVitreNative` is available. Added 1.53. */
|
|
5
|
+
export const isNativeHost = () => typeof window !== 'undefined' && window.laVitreNative != null;
|
|
6
|
+
/** `native` on a native (desktop) Vitre, `web` everywhere else. See {@link HostEnvironment}. Added 1.53. */
|
|
7
|
+
export const getHostEnvironment = () => isNativeHost() ? 'native' : 'web';
|
|
3
8
|
export const getLocalAppStorageUrl = (appId, relativePath) => `https://${appId}.local.app.lavit.re/${relativePath}`;
|
|
4
9
|
/**
|
|
5
10
|
* Promise wrapper around {@link IO.downloadFile}. Resolves to the number of
|
package/dist/Native/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../Native/index.ts"],"names":[],"mappings":"
|
|
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"]}
|
package/dist/Version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const apiVersion = "1.
|
|
1
|
+
export declare const apiVersion = "1.53.0";
|
package/dist/Version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export const apiVersion = '1.
|
|
1
|
+
export const apiVersion = '1.53.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.53.0'"]}
|