bdf.mbt 2026.11.1 → 2026.11.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +155 -8
- package/dist/browser.js +20649 -20305
- package/dist/form/form_page.js +13982 -13638
- package/dist/pdf/index.js +135 -0
- package/dist/pdf/moonbit.d.ts +68 -0
- package/dist/pdf/pdf_js.d.ts +5 -0
- package/dist/pdf/pdf_js.js +30101 -0
- package/dist/workers/native_converter_worker.js +20085 -19741
- package/docs/diagram-plugins.md +3 -4
- package/docs/format-plugin-api.md +6 -4
- package/package.json +7 -3
- package/types/pdf.d.ts +67 -0
package/README.md
CHANGED
|
@@ -4,11 +4,15 @@ Prebuilt ES modules for BDF conversion, viewing, rendering, forms, and a
|
|
|
4
4
|
versioned file-format plugin API.
|
|
5
5
|
Consumers do not need the MoonBit toolchain.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The unscoped package is published on [npm](https://www.npmjs.com/package/bdf.mbt).
|
|
8
|
+
The first release, `2026.11.1`, was published through npm Trusted Publishing.
|
|
8
9
|
The default staging package is `0.0.0-staging` with `"private": true`;
|
|
9
10
|
releases use YYYY.MM.PATCH CalVer in Asia/Tokyo and npm Trusted Publishing.
|
|
10
|
-
See the
|
|
11
|
-
The examples below
|
|
11
|
+
See [the release guide](https://github.com/f4ah6o/bdf.mbt/blob/main/docs/npm-release.md) for validation and publication.
|
|
12
|
+
The examples below pin the first public release for reproducibility, with one
|
|
13
|
+
exception: `bdf.mbt/pdf` was added after that release, so it is published from
|
|
14
|
+
the first CalVer release that includes it — not `2026.11.1`. Install without
|
|
15
|
+
the version pin (or check the published versions) when importing it.
|
|
12
16
|
|
|
13
17
|
## Package entry points
|
|
14
18
|
|
|
@@ -19,6 +23,7 @@ The examples below use a supplied local staging tarball, not a registry release.
|
|
|
19
23
|
| `bdf.mbt/workers/render` | Page rasterizing Worker. |
|
|
20
24
|
| `bdf.mbt/workers/plugin` | Prebuilt plugin Worker with the builtin DocuWorks adapter and the Excalidraw and Mermaid diagram adapters registered. |
|
|
21
25
|
| `bdf.mbt/forms` | `bdf_form_describe`, `bdf_form_fill`, `bdf_form_compile`. |
|
|
26
|
+
| `bdf.mbt/pdf` | `exportPdf`: write BDF bytes as PDF bytes with pages count, fonts count and warnings. |
|
|
22
27
|
| `bdf.mbt/xdw` | Raw `bdf_xdw_detect` and `bdf_xdw_convert` bindings. |
|
|
23
28
|
| `bdf.mbt/plugin` | Descriptor validation, registry, host, plugin types, and DocuWorks binding helpers. |
|
|
24
29
|
| `bdf.mbt/plugin/worker` | `installPluginConverterWorker`. |
|
|
@@ -29,8 +34,9 @@ The examples below use a supplied local staging tarball, not a registry release.
|
|
|
29
34
|
| `bdf.mbt/tools/emit-downstream-worker` | Node CLI script for emitting a browser-resolvable plugin Worker. |
|
|
30
35
|
|
|
31
36
|
Declarations are adjacent to the compiled bundles and in `types/index.d.ts`,
|
|
32
|
-
`types/worker.d.ts`, `types/diagram-bdf.d.ts`, `types/
|
|
33
|
-
`types/excalidraw.d.ts`, and `types/mermaid.d.ts` for
|
|
37
|
+
`types/worker.d.ts`, `types/diagram-bdf.d.ts`, `types/pdf.d.ts`,
|
|
38
|
+
`types/docuworks.d.ts`, `types/excalidraw.d.ts`, and `types/mermaid.d.ts` for
|
|
39
|
+
the typed entries.
|
|
34
40
|
Each typed entry selects its own declaration through the export map.
|
|
35
41
|
The emitter and prebuilt plugin Worker are executable scripts, not typed APIs.
|
|
36
42
|
Do not import undocumented package subpaths.
|
|
@@ -45,11 +51,11 @@ These are separate hosts, with **no automatic routing between them**.
|
|
|
45
51
|
|
|
46
52
|
## Browser quickstart: static files, no bundler
|
|
47
53
|
|
|
48
|
-
Install the
|
|
54
|
+
Install the package into your application, then copy its `dist` tree
|
|
49
55
|
unchanged into a directory your HTTP server serves:
|
|
50
56
|
|
|
51
57
|
```sh
|
|
52
|
-
npm install
|
|
58
|
+
npm install bdf.mbt@2026.11.1
|
|
53
59
|
mkdir -p public
|
|
54
60
|
cp -R node_modules/bdf.mbt/dist public/bdf.mbt-dist
|
|
55
61
|
```
|
|
@@ -238,6 +244,147 @@ pass an adapted `{ postMessage, onmessage }` target to the installer.
|
|
|
238
244
|
Do not call `bdf_create_native_converter` in Node expecting it to create a
|
|
239
245
|
`worker_threads` worker.
|
|
240
246
|
|
|
247
|
+
## PDF export: BDF bytes to PDF bytes
|
|
248
|
+
|
|
249
|
+
`exportPdf` from `bdf.mbt/pdf` writes the BDF bytes a converter or a form
|
|
250
|
+
fill produced as a PDF: it returns the PDF bytes, the page count, the count
|
|
251
|
+
of fonts used and the warnings, and leaves saving the file to the
|
|
252
|
+
caller. It runs in the browser and in Node with the same import. The entry
|
|
253
|
+
ships from the first CalVer release that includes it; the published
|
|
254
|
+
`2026.11.1` predates it:
|
|
255
|
+
|
|
256
|
+
```js
|
|
257
|
+
import { exportPdf } from "bdf.mbt/pdf";
|
|
258
|
+
|
|
259
|
+
const result = await exportPdf(bdfBytes, {
|
|
260
|
+
views: ["page1"], // optional: view ids; omit for every view
|
|
261
|
+
tagged: false, // reserved; the writer warns when true
|
|
262
|
+
compress: false, // reserved; content streams stay uncompressed
|
|
263
|
+
fallbackFont: fontBytes, // optional: a TrueType/OpenType program
|
|
264
|
+
});
|
|
265
|
+
console.log(`${result.pages} pages, ${result.fonts} fonts, ${result.warnings.length} warnings`);
|
|
266
|
+
if (result.warnings.length > 0) {
|
|
267
|
+
for (const warning of result.warnings) console.warn(`PDF: ${warning}`);
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
The conversion runs synchronously in the calling thread; the returned
|
|
272
|
+
promise resolves as soon as the bytes are written. The input is only read:
|
|
273
|
+
its buffer is never modified or detached. `result.fonts` counts the fonts
|
|
274
|
+
the PDF uses — the PDF standard font counts, though no program of it is
|
|
275
|
+
embedded — and unknown option keys are ignored, so a misspelled option
|
|
276
|
+
(JavaScript) or field (the options JSON of the compiled bridge) falls back
|
|
277
|
+
to its default silently; the TypeScript declarations reject them.
|
|
278
|
+
|
|
279
|
+
### Fallback fonts and Japanese
|
|
280
|
+
|
|
281
|
+
The text of a document that carries fonts of its own is drawn with those
|
|
282
|
+
fonts' embedded subsets. The text that does not — the text of a form fill,
|
|
283
|
+
and any text whose own font the document does not name — needs a fallback
|
|
284
|
+
font: pass its program (`Uint8Array` bytes of a licensed TrueType or
|
|
285
|
+
OpenType font you provide) as `fallbackFont`, and the writer embeds only
|
|
286
|
+
the subset of its glyphs that the document's text uses. Without one, that
|
|
287
|
+
text is drawn with the PDF standard font, whose codeset covers plain ASCII:
|
|
288
|
+
every other character is written as `?` and the result warns about exactly
|
|
289
|
+
which characters. A supplied font the writer cannot read also warns.
|
|
290
|
+
A single fallback font does not reproduce a document's regular and bold
|
|
291
|
+
faces: one program stands in for them all.
|
|
292
|
+
|
|
293
|
+
Rejects — never an empty PDF as a success — cover the wrong argument types,
|
|
294
|
+
a BDF that cannot be read, a requested view the document does not have,
|
|
295
|
+
and a selection of views that holds no page (a sheet view, for example).
|
|
296
|
+
|
|
297
|
+
### Browser: save with a Blob
|
|
298
|
+
|
|
299
|
+
A fixed-form office template (`.docx`) fills to a document whose views hold
|
|
300
|
+
pages, which is the pipeline this entry exists for. The same applies to the
|
|
301
|
+
grid text templates. Do not feed it a spreadsheet fill expecting pages: a
|
|
302
|
+
sheet view holds no page and the export rejects it (see above).
|
|
303
|
+
|
|
304
|
+
```html
|
|
305
|
+
<script type="module">
|
|
306
|
+
import { bdf_form_fill } from "/bdf.mbt-dist/form/form_page.js";
|
|
307
|
+
import { exportPdf } from "/bdf.mbt-dist/pdf/index.js";
|
|
308
|
+
|
|
309
|
+
// your licensed TrueType/OpenType font for the filled text (Japanese needs one)
|
|
310
|
+
const fontBytes = await (await fetch("/assets/your-licensed-font.ttf")).arrayBuffer();
|
|
311
|
+
// an office form template such as the form's samples: a .docx (or a text template)
|
|
312
|
+
const template = new Uint8Array(await (await fetch("/templates/slip.docx")).arrayBuffer());
|
|
313
|
+
const filled = JSON.parse(bdf_form_fill(template, JSON.stringify({
|
|
314
|
+
customer: "株式会社みなと商事", // your data, against the template's tags
|
|
315
|
+
}), "[]", false));
|
|
316
|
+
if (!filled.ok) throw new Error(filled.error);
|
|
317
|
+
const bdf = Uint8Array.from(atob(filled.bdf), ch => ch.charCodeAt(0));
|
|
318
|
+
const result = await exportPdf(bdf, { fallbackFont: new Uint8Array(fontBytes) });
|
|
319
|
+
if (result.warnings.length > 0) {
|
|
320
|
+
for (const warning of result.warnings) console.warn(warning);
|
|
321
|
+
// tell the user: a warning means the PDF omits what it says
|
|
322
|
+
}
|
|
323
|
+
const blob = new Blob([result.bytes], { type: "application/pdf" });
|
|
324
|
+
const link = document.querySelector("#download");
|
|
325
|
+
link.href = URL.createObjectURL(blob);
|
|
326
|
+
link.download = "slip.pdf";
|
|
327
|
+
</script>
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
The browser smoke of the repository's library test suite exercises this
|
|
331
|
+
pipeline against a converted document with a consumer-passed font; the
|
|
332
|
+
installed Node suite exercises the same office-template fill (a multi-page
|
|
333
|
+
`.docx` whose Japanese comes back in the written PDF).
|
|
334
|
+
|
|
335
|
+
### Node: save to a file
|
|
336
|
+
|
|
337
|
+
```js
|
|
338
|
+
import { readFile, writeFile } from "node:fs/promises";
|
|
339
|
+
import { exportPdf } from "bdf.mbt/pdf";
|
|
340
|
+
|
|
341
|
+
const [input, output, font] = process.argv.slice(2);
|
|
342
|
+
if (!input || !output || !font) {
|
|
343
|
+
throw new Error("Usage: node export-pdf.mjs INPUT.bdf OUTPUT.pdf FONT.ttf");
|
|
344
|
+
}
|
|
345
|
+
const result = await exportPdf(new Uint8Array(await readFile(input)), {
|
|
346
|
+
fallbackFont: new Uint8Array(await readFile(font)), // or omit for ASCII-only text
|
|
347
|
+
});
|
|
348
|
+
for (const warning of result.warnings) console.warn(`PDF: ${warning}`); // never hide these
|
|
349
|
+
await writeFile(output, result.bytes, { flag: "wx" }); // Do not overwrite a file.
|
|
350
|
+
console.log(`${output}: ${result.pages} pages, ${result.fonts} fonts`);
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
A form-filled BDF connects through `bdf.mbt/forms` (`bdf_form_fill` returns
|
|
354
|
+
the BDF the example above exports, base64 in its envelope). The raw
|
|
355
|
+
`bdf.mbt/xdw` and plugin API outputs are the same BDF bytes, and so is any
|
|
356
|
+
converted document; every route produces the same input for `exportPdf`.
|
|
357
|
+
|
|
358
|
+
### What the writer reproduces
|
|
359
|
+
|
|
360
|
+
| Reproduced | Notes |
|
|
361
|
+
| --- | --- |
|
|
362
|
+
| Page size, view selection | Page-less views warn; a selection with no page rejects. |
|
|
363
|
+
| Text, cells of a form grid, floats in Japanese | Drawn with the document's fonts, or the `fallbackFont` subset. |
|
|
364
|
+
| Vector paths, fills, colors, links | As the writer draws them. |
|
|
365
|
+
| Annotations of a link, document metadata title and author | Link targets come from the document. |
|
|
366
|
+
|
|
367
|
+
| Not reproduced (the result warns) | Message |
|
|
368
|
+
| --- | --- |
|
|
369
|
+
| Images | `an image is omitted` |
|
|
370
|
+
| Cropped images | `a cropped image is omitted` |
|
|
371
|
+
| Shadows | `a shadow is omitted` |
|
|
372
|
+
| Image filters | `an image filter is omitted` |
|
|
373
|
+
| Gradients | `gradients are approximated with a solid colour` |
|
|
374
|
+
| Pattern fills | `a pattern fill is drawn with its solid colour` |
|
|
375
|
+
| Masks | `a mask is omitted; its mask content is not drawn` |
|
|
376
|
+
| Tagged structure (`tagged: true`) | `tagged PDF structure is not written yet` |
|
|
377
|
+
| Characters the fallback font lacks | `the fallback font has no glyph for: …` |
|
|
378
|
+
| An unreadable fallback font | `the fallback font could not be read` / `could not be subset` |
|
|
379
|
+
| A font whose license forbids embedding | `… is not embedded: its license does not allow embedding` |
|
|
380
|
+
| Characters written as `?` without a usable font | `text without a font of its own is drawn with the PDF standard font, which has no glyph for: …` |
|
|
381
|
+
| Deeply nested or broken objects | `objects draw objects too deep`, `an object could not be read`, `a child object could not be read`, `a layer could not be read`, `a path could not be read`, `a clip path could not be read` |
|
|
382
|
+
|
|
383
|
+
Treat any warning as a visible omission: a result with warnings is not a
|
|
384
|
+
faithful reproduction of the source document, so surfaces that show it
|
|
385
|
+
should say so. Tagged/PDF-A signatures, images and Office round-trips are
|
|
386
|
+
outside this writer's scope.
|
|
387
|
+
|
|
241
388
|
## TypeScript plugin checking
|
|
242
389
|
|
|
243
390
|
Import types from `bdf.mbt/plugin`; the installer and DocuWorks adapter have
|
|
@@ -289,7 +436,7 @@ Run `npx tsc --project tsconfig.json`, then use the emitter with
|
|
|
289
436
|
The type-only import disappears from the generated module, leaving no bare
|
|
290
437
|
runtime import for the browser to resolve.
|
|
291
438
|
`apiVersion: 1` is the contract version, separate from the npm package's
|
|
292
|
-
staging or
|
|
439
|
+
staging or release version.
|
|
293
440
|
Generated browser-client types currently return `any`; plugin descriptors have
|
|
294
441
|
the more specific declarations shown here.
|
|
295
442
|
|