bdf.mbt 2026.11.1 → 2026.11.3

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
@@ -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
- **Release artifact 2026.11.1.** The selected package name is `bdf.mbt`.
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 repository release guide for setup and the initial-publication step.
11
- The examples below use a supplied local staging tarball, not a registry release.
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/docuworks.d.ts`,
33
- `types/excalidraw.d.ts`, and `types/mermaid.d.ts` for the plugin entries.
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 supplied tarball into your application, then copy its `dist` tree
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 ./bdf.mbt-0.0.0-staging.tgz
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 eventual release version.
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