@twip/web 0.0.0-canary-05bfdb9 → 0.0.0-canary-1644e0a

package/README.md

@@ -32,4 +32,41 @@ await editor.destroy();
 
 In Node, workers and tests, `HeadlessEditor.create()` gives the same API with no DOM.
 
+## Your own field types
+
+A field whose type isn't one of Word's reads as a bookmark reference, and with no result it shows "Error! Bookmark
+not defined.", as in Word. Declare the types your application fills itself after each `open`:
+
+```ts
+await editor.commands.setApplicationFieldTypes({ types: ['CUSTOMVALUE', 'CUSTOMTEXT'] });
+```
+
+Their fields then keep their results, show nothing when empty (their `setFieldLabels` label, else «first argument»,
+in design mode) and are listed by `fieldsUpdateRequested` on `updateFields`, for `setFieldResults` to fill. Types
+compare without case; each call replaces the list, and `[]` clears it. Setting it doesn't mark the document modified.
+
+## Serving the engine's files yourself
+
+The engine runs from files in the package's `dist/`: `worker.js`, `twip-wasm.js`, `twip_wasm.wasm`, and the
+`transport/` and `worker/` folders the worker imports. By default the SDK finds them beside its own code, through
+`new URL(..., import.meta.url)`. If your bundler doesn't follow those (Angular's esbuild builder doesn't), copy
+`dist/` as it is to a folder you serve, and say where, once, before the first `FontLibrary` call or editor:
+
+```ts
+import { configure } from '@twip/web';
+
+configure({ assets: new URL('twip/', document.baseURI) }); // or a CDN: 'https://cdn.example.com/twip/'
+```
+
+`assets` may be on another origin. The worker then starts from a same-origin `blob:` module that imports
+`worker.js`, so the other origin must:
+
+- send `Access-Control-Allow-Origin` (your page's origin, or `*`) on every file in the folder, as module scripts and
+  the WebAssembly are fetched with CORS;
+- serve `twip_wasm.wasm` as `application/wasm`, or the engine compiles it after a full download instead of while
+  streaming.
+
+With a Content Security Policy, allow `blob:` in `worker-src`, the other origin in `script-src` and `connect-src`, and
+`'wasm-unsafe-eval'` in `script-src` (which the engine needs on any origin).
+
 Guides: https://jaxcksn.github.io/twip/docs/guides/web. Licensed under Apache-2.0.

package/dist/commands.d.ts

@@ -508,6 +508,15 @@ export interface Commands {
     setSubTemplateRules(options: {
         rules: ReferenceRule[];
     }): Promise<void>;
+    /**
+     * The application's own field types (a code's first word, compared without case), replacing those set before:
+     * their fields keep their results, show their labels in design mode ({@link Commands.setFieldLabels}, else
+     * «first argument»), are listed by `fieldsUpdateRequested` and are never read as bookmark references
+     * ("Error! Bookmark not defined."). `[]` clears them. Set it after each `open`, as the rules. View.
+     */
+    setApplicationFieldTypes(options: {
+        types: string[];
+    }): Promise<void>;
     /** Shows references' sub-template bodies in their place, or their fields (default: every reference). View. */
     setSubTemplateView(options: {
         ids?: ElementId[];

package/dist/commands.js

@@ -146,6 +146,7 @@ const encodings = {
     setFieldTypes: 'spread',
     setUnmappedFields: 'spread',
     setSubTemplateRules: 'spread',
+    setApplicationFieldTypes: 'spread',
     setSubTemplateView: 'spread',
     editSubTemplate: 'spread',
     closeSubTemplate: 'none',

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  * @packageDocumentation
  */
 export { Editor, HeadlessEditor } from './editor.js';
+export { configure } from './transport/module.js';
 export type { ExportOptions, ExportResult, MountOptions, PdfOptions, SessionOptions } from './editor.js';
 export type { CommandEntry, CommandId, CommandInfo, Commands, FieldTargets, NoArgumentCommandId, Op, OpArgs, PlaceholderAction, PlaceholderLook, } from './commands.js';
 export type { AutoCorrectChange, AutoCorrectEntry, AutoCorrectOptions, CharacterFormatting, CommandState, CommandValues, EditingTarget, EditorState, ElementContext, HighlightColor, HorizontalPosition, HorizontalReference, LineSpacing, MarkupView, Mixed, ObjectHorizontalAlignment, ObjectPlacement, ObjectSelection, ObjectVerticalAlignment, ObjectWrap, PageFormatting, ParagraphFormatting, ReviewState, RowHeight, SelectionSummary, TablePosition, TableSelection, TableStyleOptions, TableWidth, TextDistance, Tri, UnderlineStyle, VerticalPosition, VerticalReference, ViewState, WrapSide, } from './state.js';

package/dist/index.js

@@ -5,6 +5,7 @@
  * @packageDocumentation
  */
 export { Editor, HeadlessEditor } from './editor.js';
+export { configure } from './transport/module.js';
 export { EditorError } from './errors.js';
 export { FontLibrary } from './fonts/library.js';
 export { cm, inches, mm, pt } from './types.js';

package/dist/transport/module.d.ts

@@ -47,6 +47,22 @@ export interface TwipModule {
         deleteContext(handle: number): void;
     };
 }
+/**
+ * Sets where the package's runtime files (dist/: worker.js, twip-wasm.js, twip_wasm.wasm, transport/ and worker/) are
+ * served from, for an application whose bundler doesn't follow `new URL(..., import.meta.url)`. Call it once, before
+ * anything starts the engine: the first {@link FontLibrary} call, {@link Editor.mount} or
+ * {@link HeadlessEditor.create}. The engine is shared by every session, so it's not a per-session option.
+ *
+ * `assets` is the folder, resolved against the document's base URL. It may be on another origin (a CDN), which must
+ * then send CORS headers for every file; see the package README.
+ *
+ * @throws {@link EditorError} `not-allowed` when the engine has already loaded from another folder.
+ */
+export declare function configure(options: {
+    assets: string | URL;
+}): void;
+/** The configured assets folder, if any, read to start the engine: it can't change after this. */
+export declare function useAssets(): URL | undefined;
 /** Instantiates the engine module, with `dispatch` registered before any engine call can call back. */
 export declare function loadModule(dispatch: NonNullable<TwipModule['twipDispatch']>): Promise<TwipModule>;
 export {};

package/dist/transport/module.js

@@ -1,15 +1,49 @@
 // Loading the engine module: the one place that knows where the WebAssembly build is and what it exports.
 // The build copies the emscripten output (twip-wasm.js and twip_wasm.wasm) next to dist/index.js.
+import { EditorError } from '../errors.js';
 /**
- * Where the engine module and its WebAssembly are, relative to this file in dist/transport/. Both are literal
- * `new URL(..., import.meta.url)`s, so a bundler copies both files into the application's build.
+ * Where the engine module and its WebAssembly are by default: relative to this file in dist/transport/. Both are
+ * literal `new URL(..., import.meta.url)`s, so a bundler that follows them copies both files into the application's
+ * build. {@link configure}'s `assets` replaces them.
  */
-const moduleUrl = new URL('../twip-wasm.js', import.meta.url);
-const wasmUrl = new URL('../twip_wasm.wasm', import.meta.url);
+const defaultModuleUrl = new URL('../twip-wasm.js', import.meta.url);
+const defaultWasmUrl = new URL('../twip_wasm.wasm', import.meta.url);
+/** The folder of the package's dist/ files, when the application set one. */
+let assets;
+/** Whether this thread has read `assets` to start the engine: it can't change after. */
+let used = false;
+/**
+ * Sets where the package's runtime files (dist/: worker.js, twip-wasm.js, twip_wasm.wasm, transport/ and worker/) are
+ * served from, for an application whose bundler doesn't follow `new URL(..., import.meta.url)`. Call it once, before
+ * anything starts the engine: the first {@link FontLibrary} call, {@link Editor.mount} or
+ * {@link HeadlessEditor.create}. The engine is shared by every session, so it's not a per-session option.
+ *
+ * `assets` is the folder, resolved against the document's base URL. It may be on another origin (a CDN), which must
+ * then send CORS headers for every file; see the package README.
+ *
+ * @throws {@link EditorError} `not-allowed` when the engine has already loaded from another folder.
+ */
+export function configure(options) {
+    const url = new URL(options.assets, globalThis.document?.baseURI ?? globalThis.location?.href);
+    if (!url.pathname.endsWith('/'))
+        url.pathname += '/';
+    if (used && url.href !== assets?.href) {
+        throw new EditorError('not-allowed', 'configure() must be called before the first FontLibrary call or editor: the engine has already loaded');
+    }
+    assets = url;
+}
+/** The configured assets folder, if any, read to start the engine: it can't change after this. */
+export function useAssets() {
+    used = true;
+    return assets;
+}
 /** Instantiates the engine module, with `dispatch` registered before any engine call can call back. */
 export async function loadModule(dispatch) {
+    const assets = useAssets();
+    const moduleUrl = assets ? new URL('twip-wasm.js', assets) : defaultModuleUrl;
+    const wasmUrl = assets ? new URL('twip_wasm.wasm', assets) : defaultWasmUrl;
     const { default: create } = (await import(moduleUrl.href));
-    // In Node the module finds its file itself; in a browser it's wherever the bundler put it.
+    // In Node the module finds its file itself; in a browser it's wherever the bundler, or `assets`, put it.
     const locateFile = moduleUrl.protocol === 'file:' ? undefined : (file) => (file.endsWith('.wasm') ? wasmUrl : new URL(file, moduleUrl)).href;
     const module = await create({ twipDispatch: dispatch, locateFile });
     module.twipDispatch = dispatch;

package/dist/transport/worker.js

@@ -5,6 +5,7 @@
 // cache before any event of the same drain.
 import { EditorError, unsupported } from '../errors.js';
 import { live } from '../host/dom.js';
+import { useAssets } from './module.js';
 import { Method, toError } from './protocol.js';
 let modules;
 /** Whether this page can run the engine in a worker: module workers and `transferControlToOffscreen`. */
@@ -43,6 +44,26 @@ export function chooseExecution(execution = 'auto') {
         throw unsupported("execution: 'worker' on this browser");
     return 'main';
 }
+/**
+ * Starts the engine worker. With no `assets`, it's beside this file's directory, in dist/: written out in one
+ * expression, as bundlers recognise it and build the worker and its imports into the application. With `assets`, it's
+ * there, told the folder in its URL's query (worker.ts); on another origin, through a same-origin module that imports
+ * it, as a worker's script must come from the page's origin.
+ */
+function startWorker(assets) {
+    if (!assets)
+        return new Worker(new URL('../worker.js', import.meta.url), { type: 'module', name: 'twip-engine' });
+    const url = new URL(`worker.js?assets=${encodeURIComponent(assets.href)}`, assets);
+    if (url.origin === location.origin)
+        return new Worker(url, { type: 'module', name: 'twip-engine' });
+    const bootstrap = URL.createObjectURL(new Blob([`import ${JSON.stringify(url.href)};`], { type: 'text/javascript' }));
+    const worker = new Worker(bootstrap, { type: 'module', name: 'twip-engine' });
+    // Fetched by the time the worker answers, or fails.
+    const revoke = () => URL.revokeObjectURL(bootstrap);
+    worker.addEventListener('message', revoke, { once: true });
+    worker.addEventListener('error', revoke, { once: true });
+    return worker;
+}
 let shared;
 /** The page's one worker transport. */
 export function workerTransport() {
@@ -139,9 +160,7 @@ export class WorkerTransport {
     #start() {
         if (this.#worker)
             return this.#worker;
-        // The worker is beside this file's directory, in dist/. Written out in one expression, as bundlers recognise
-        // it: they build the worker and its imports into the application.
-        const worker = new Worker(new URL('../worker.js', import.meta.url), { type: 'module', name: 'twip-engine' });
+        const worker = startWorker(useAssets());
         live.workers++;
         worker.onmessage = ({ data }) => this.#receive(data);
         worker.onerror = (e) => {

package/dist/worker/entry.js

@@ -6,7 +6,6 @@
 import { EditorError } from '../errors.js';
 import { directTransport } from '../transport/direct.js';
 import { fromError } from '../transport/protocol.js';
-const engine = directTransport();
 const signals = new Map();
 /** Posts to the page, moving the buffer of exported bytes instead of copying it. */
 function post(message) {
@@ -35,8 +34,16 @@ function run(t, { id, op, args }) {
             return t[op].apply(t, args);
     }
 }
-// Session 0 is the engine's own: font requests.
-engine.then((t) => t.listen(0, post), () => { });
+let started;
+/** The engine, loaded on the first request: by then worker.ts has applied the page's `assets`. */
+function engine() {
+    if (!started) {
+        started = directTransport();
+        // Session 0 is the engine's own: font requests.
+        started.then((t) => t.listen(0, post), () => { });
+    }
+    return started;
+}
 onmessage = ({ data }) => {
     if (data.op === 'abort') {
         signals.get(data.id)?.abort();
@@ -44,7 +51,7 @@ onmessage = ({ data }) => {
     }
     // Every request waits on the same promise, so they reach the engine's queue in arrival order. Id 0 is a replayed
     // library change: nothing waits for its reply.
-    engine.then((t) => run(t, data)).then((ok) => data.id && post({ id: data.id, ok }), (e) => {
+    engine().then((t) => run(t, data)).then((ok) => data.id && post({ id: data.id, ok }), (e) => {
         if (!data.id)
             return console.error(e);
         const error = e instanceof EditorError ? e : new EditorError('internal', String(e), { cause: e });

package/dist/worker.js

@@ -1,2 +1,8 @@
 // The page's engine worker entry (`@twip/web/worker.js`). The SDK starts it itself; applications never load it.
 import './worker/entry.js';
+import { configure } from './transport/module.js';
+// The page's `assets` (configure()), in the query it started this worker with: the engine loads from there, not from
+// this file's own URL. Applied before the first request, which loads the engine (worker/entry.ts).
+const assets = new URL(import.meta.url).searchParams.get('assets');
+if (assets)
+    configure({ assets });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twip/web",
-  "version": "0.0.0-canary-05bfdb9",
+  "version": "0.0.0-canary-1644e0a",
   "description": "The Twip DOCX editor for the browser and Node: a managed, framework-independent editor over the WebAssembly engine.",
   "type": "module",
   "license": "Apache-2.0",