@weasel-js/pdf 0.0.0-stage → 1.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @weasel-js/pdf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+PDF documents from weasel draw commands: vector paths, shadings, images, and
+embedded fonts with selectable text. No scene graph, no React.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/#pkg/pdf).
+
+## Install
+
+```sh
+npm install @weasel-js/pdf
+```
+
+## Usage
+
+```ts
+import { registryFontSource, writePdf } from '@weasel-js/pdf';
+
+const { bytes, skipped } = await writePdf(
+  [{ width: 612, height: 792, commands }],
+  { fonts: registryFontSource, title: 'Chart' },
+);
+```
+
+Page units are points, with the origin at the top left and y growing downward.
+`registryFontSource` reads the faces registered with `@weasel-js/font`, whose
+outlines must be registered for text to embed. `writePdf` rejects an empty
+page list.
+
+## What is drawn
+
+Written natively, as vectors: paths, solid fills, gradient shadings (with soft
+masks for transparency), strokes (native, or outlined where PDF cannot express
+them) with their markers, images, sprites, tiling patterns, text as Type0 fonts
+with a ToUnicode map, color matrices, and isolated groups.
+
+Handed to the `rasterize` hook: effects groups, shader commands, and fills in
+a registered paint kind. Without a hook they are skipped.
+
+```ts
+rasterize(commands, rect, scale, view) => Promise<{ width, height, data }>
+```
+
+`rect` is the region in page points, `scale` the pixels per point, and `view`
+the page's `view`, which `world`-unit paint in `commands` resolves through.
+`data` is straight RGBA, top-down.
+
+A face that is CFF-only, restricted (`fsType` 0x0002), bitmap-only (`fsType`
+0x0200), registered from a WOFF file, or unreadable is drawn as glyph outlines
+instead, so its text is not selectable.
+
+## `skipped`
+
+Each entry is `{ kind: 'glyph' | 'command', detail }`. It reports:
+
+- an effects group, shader command or registered-paint fill with no `rasterize` hook, or one whose hook threw or returned the wrong number of pixels;
+- an image that could not be read, and a texture that cannot be drawn;
+- a glyph nothing can draw: a color glyph, a slot the layout left empty, or one with no outline in the outline fallback;
+- a command holding NaN or an infinity, which is left out whole;
+- the approximations below, except the stroke width and `screen`-unit paint.
+
+## Known approximations
+
+- A `{ px }` stroke width under an anisotropic view uses the mean scale.
+- A `vertexColors` stroke uses a single paint, and a `vertexColors` fill its solid fill.
+- `screen`-unit paint inside a rasterized group is placed in the raster's pixels, not the page's points.
+- A Porter-Duff composite is drawn source-over.
+- An isolated group's color matrix alpha offset is not drawn.

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { FontStyle, FaceEmbedding } from '@weasel-js/font';
+import { GlMat3 } from '@weasel-js/geom';
+import { DrawCommand } from '@weasel-js/renderer';
+
+/** Where the writer gets the font faces it embeds and the glyph outlines it falls back to; `registryFontSource` reads the font registry. */
+interface PdfFontSource {
+    embedding(family: string, weight: number, style: FontStyle): Promise<FaceEmbedding | null>;
+    /** Em-space SVG path data, as glyphOutline answers it. */
+    outline(family: string, weight: number, style: FontStyle, cp: number): string | null;
+}
+/** The faces registered with `@weasel-js/font`. */
+declare const registryFontSource: PdfFontSource;
+
+/** An axis-aligned rectangle in page units. */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** One page of the document: its size in points and the draw commands painted onto it. */
+interface PdfPage {
+    width: number;
+    height: number;
+    commands: readonly DrawCommand[];
+    view?: GlMat3;
+}
+/** A decoded bitmap handed back by the host, for images and paints the PDF cannot express directly. */
+interface RasterPixels {
+    width: number;
+    height: number;
+    /** Straight RGBA, top-down. */
+    data: Uint8ClampedArray;
+}
+/** Settings and host callbacks for `writePdf`; only `fonts` is required. */
+interface WritePdfOptions {
+    fonts: PdfFontSource;
+    title?: string;
+    /** Default true; unit tests pass false because jsdom realms lack `CompressionStream`. */
+    compress?: boolean;
+    readPixels?: (image: ImageBitmap | HTMLImageElement) => RasterPixels;
+    /** `view` is the page's `PdfPage.view`: what a `world`-unit paint in `commands` resolves through. */
+    rasterize?: (commands: readonly DrawCommand[], rect: Rect, scale: number, view: GlMat3 | undefined) => Promise<RasterPixels>;
+}
+/** A glyph or command the writer left out of the file, with the reason. */
+interface PdfSkip {
+    kind: 'glyph' | 'command';
+    detail: string;
+}
+/** The finished file and everything the writer had to leave out of it. */
+interface PdfResult {
+    bytes: Uint8Array;
+    skipped: readonly PdfSkip[];
+}
+/** One PDF page per entry of `pages`, which must hold at least one. */
+declare function writePdf(pages: readonly PdfPage[], opts: WritePdfOptions): Promise<PdfResult>;
+
+export { type PdfFontSource, type PdfPage, type PdfResult, type PdfSkip, type RasterPixels, type Rect, type WritePdfOptions, registryFontSource, writePdf };