cink 0.1.4__tar.gz

cink-0.1.4/.gitignore

@@ -0,0 +1,10 @@
+/target/
+node_modules/
+
+# Generated release outputs
+**/dist/
+**/LICENSES/
+!LICENSES/
+*.tgz
+__pycache__/
+*.egg-info/

cink-0.1.4/LICENSES/Apache-2.0.txt

@@ -0,0 +1,204 @@
+Copyright 2026 Julian Y. Richard Corbet
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cink-0.1.4/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: cink
+Version: 0.1.4
+Summary: Handwritten signature image rendering for correspondence. Pixels, not signatures
+Project-URL: Homepage, https://github.com/corbet-labs/cink#readme
+Project-URL: Repository, https://github.com/corbet-labs/cink
+Project-URL: Issues, https://github.com/corbet-labs/cink/issues
+License-Expression: Apache-2.0
+License-File: LICENSES/Apache-2.0.txt
+Keywords: correspondence,i18n,locale
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cink
+
+**Prepare handwritten signature images for correspondence.**
+
+[![crates.io](https://img.shields.io/crates/v/cink.svg)](https://crates.io/crates/cink) [![npm](https://img.shields.io/npm/v/@corbet-labs/cink.svg)](https://www.npmjs.com/package/@corbet-labs/cink) [![Rust API](https://docs.rs/cink/badge.svg)](https://docs.rs/cink)
+
+Recognize PNG, JPEG, and SVG input, inspect raster dimensions, calculate an aspect-preserving size, and generate a Typst image call. Runs without an image-decoding library.
+
+```js
+import { imageSnippet } from '@corbet-labs/cink';
+
+imageSnippet('/signature.png', 31.5);
+// #image("/signature.png", height: 31.5pt)
+```
+
+## Install
+
+| Environment | Command |
+| --- | --- |
+| Rust / Cargo | `cargo add cink` |
+| Node.js / npm | `npm install @corbet-labs/cink` |
+| pnpm | `pnpm add @corbet-labs/cink` |
+| Yarn | `yarn add @corbet-labs/cink` |
+| Bun | `bun add @corbet-labs/cink` |
+| Deno | `deno add npm:@corbet-labs/cink` |
+
+The 0.1.4 JavaScript distribution includes compiled ESM, CommonJS,
+TypeScript declarations, and a standalone browser module. Node.js 20+ is
+supported; no TypeScript loader is required.
+
+```js
+// CommonJS
+const { imageSnippet } = require('@corbet-labs/cink');
+```
+
+```html
+<script type="module">
+  import { imageSnippet } from 'https://cdn.jsdelivr.net/npm/@corbet-labs/cink@0.1.4/dist/browser.js';
+  console.log(imageSnippet('/signature.png', 31.5));
+</script>
+```
+
+Python wheels, source distributions, and CLI instructions are in the
+[installation guide](https://github.com/corbet-labs/cink/blob/main/docs/installation.md).
+JSR publication and Typst availability are listed there explicitly.
+
+## Rust
+
+```rust
+use cink::image_snippet;
+
+assert_eq!(image_snippet("/signature.png", 31.5, None), "#image(\"/signature.png\", height: 31.5pt)");
+```
+
+## Python
+
+```python
+from cink import image_snippet
+
+assert image_snippet("/signature.png", 31.5) == '#image("/signature.png", height: 31.5pt)'
+```
+
+## API
+
+| JavaScript / Python or Rust | Purpose |
+| --- | --- |
+| `normalize` | Recognize a base64 image or data URL |
+| `exceedsLimits` / `exceeds_limits` | Check a raster pixel budget |
+| `scaleToFit` / `scale_to_fit` | Calculate a downscaling factor |
+| `signatureSize` / `signature_size` | Fit dimensions to a point size |
+| `imageSnippet` / `image_snippet` | Generate a Typst image call |
+
+Base64 input uses the standard alphabet, required padding, and canonical trailing bits; embedded whitespace is rejected.
+
+PNG and JPEG dimensions are read from headers; this is not a full raster integrity check. SVG passes through without sanitization or known dimensions. Unrecognized headers and unsupported formats return `null`/`None`. Nonpositive, nonfinite, and unrepresentable requested sizes return `null`/`None`. Resampling and placement belong to the caller. These are handwriting images, not cryptographic or electronic signatures.
+
+## Correspondence family
+
+| Library | Responsibility |
+| --- | --- |
+| [cletter](https://github.com/corbet-labs/cletter) | Compose the correspondence helpers |
+| [cgreet](https://github.com/corbet-labs/cgreet) | German salutations and titles |
+| [cfarewell](https://github.com/corbet-labs/cfarewell) | Locale-specific closings |
+| [cdate](https://github.com/corbet-labs/cdate) | Calendar-date formatting |
+| [cink](https://github.com/corbet-labs/cink) | Handwritten signature images |
+
+
+## Development
+
+Behavior is defined by [the locale tables](https://github.com/corbet-labs/cink/tree/main/tables)
+and [shared conformance vectors](https://github.com/corbet-labs/cink/tree/main/tests/vectors).
+Rust, JavaScript, and Python run the same vectors. Selected CI checks exercise
+installed JavaScript tarballs, Python wheels and command-line entrypoints, and
+Typst packages. Release validation records the actual runtime and platform;
+Linux results do not establish native Windows or macOS coverage.
+All five Rust crates forbid unsafe code in their own source.
+
+See [the release guide](https://github.com/corbet-labs/cink/blob/main/docs/releasing.md)
+for generation, verification, and publication commands.
+
+## License
+
+Copyright 2026 Julian Y. Richard Corbet. cink 0.1.4 is licensed under [Apache-2.0](https://github.com/corbet-labs/cink/blob/main/LICENSES/Apache-2.0.txt). Previously published versions retain their original license grants.

cink-0.1.4/README.md

@@ -0,0 +1,103 @@
+# cink
+
+**Prepare handwritten signature images for correspondence.**
+
+[![crates.io](https://img.shields.io/crates/v/cink.svg)](https://crates.io/crates/cink) [![npm](https://img.shields.io/npm/v/@corbet-labs/cink.svg)](https://www.npmjs.com/package/@corbet-labs/cink) [![Rust API](https://docs.rs/cink/badge.svg)](https://docs.rs/cink)
+
+Recognize PNG, JPEG, and SVG input, inspect raster dimensions, calculate an aspect-preserving size, and generate a Typst image call. Runs without an image-decoding library.
+
+```js
+import { imageSnippet } from '@corbet-labs/cink';
+
+imageSnippet('/signature.png', 31.5);
+// #image("/signature.png", height: 31.5pt)
+```
+
+## Install
+
+| Environment | Command |
+| --- | --- |
+| Rust / Cargo | `cargo add cink` |
+| Node.js / npm | `npm install @corbet-labs/cink` |
+| pnpm | `pnpm add @corbet-labs/cink` |
+| Yarn | `yarn add @corbet-labs/cink` |
+| Bun | `bun add @corbet-labs/cink` |
+| Deno | `deno add npm:@corbet-labs/cink` |
+
+The 0.1.4 JavaScript distribution includes compiled ESM, CommonJS,
+TypeScript declarations, and a standalone browser module. Node.js 20+ is
+supported; no TypeScript loader is required.
+
+```js
+// CommonJS
+const { imageSnippet } = require('@corbet-labs/cink');
+```
+
+```html
+<script type="module">
+  import { imageSnippet } from 'https://cdn.jsdelivr.net/npm/@corbet-labs/cink@0.1.4/dist/browser.js';
+  console.log(imageSnippet('/signature.png', 31.5));
+</script>
+```
+
+Python wheels, source distributions, and CLI instructions are in the
+[installation guide](https://github.com/corbet-labs/cink/blob/main/docs/installation.md).
+JSR publication and Typst availability are listed there explicitly.
+
+## Rust
+
+```rust
+use cink::image_snippet;
+
+assert_eq!(image_snippet("/signature.png", 31.5, None), "#image(\"/signature.png\", height: 31.5pt)");
+```
+
+## Python
+
+```python
+from cink import image_snippet
+
+assert image_snippet("/signature.png", 31.5) == '#image("/signature.png", height: 31.5pt)'
+```
+
+## API
+
+| JavaScript / Python or Rust | Purpose |
+| --- | --- |
+| `normalize` | Recognize a base64 image or data URL |
+| `exceedsLimits` / `exceeds_limits` | Check a raster pixel budget |
+| `scaleToFit` / `scale_to_fit` | Calculate a downscaling factor |
+| `signatureSize` / `signature_size` | Fit dimensions to a point size |
+| `imageSnippet` / `image_snippet` | Generate a Typst image call |
+
+Base64 input uses the standard alphabet, required padding, and canonical trailing bits; embedded whitespace is rejected.
+
+PNG and JPEG dimensions are read from headers; this is not a full raster integrity check. SVG passes through without sanitization or known dimensions. Unrecognized headers and unsupported formats return `null`/`None`. Nonpositive, nonfinite, and unrepresentable requested sizes return `null`/`None`. Resampling and placement belong to the caller. These are handwriting images, not cryptographic or electronic signatures.
+
+## Correspondence family
+
+| Library | Responsibility |
+| --- | --- |
+| [cletter](https://github.com/corbet-labs/cletter) | Compose the correspondence helpers |
+| [cgreet](https://github.com/corbet-labs/cgreet) | German salutations and titles |
+| [cfarewell](https://github.com/corbet-labs/cfarewell) | Locale-specific closings |
+| [cdate](https://github.com/corbet-labs/cdate) | Calendar-date formatting |
+| [cink](https://github.com/corbet-labs/cink) | Handwritten signature images |
+
+
+## Development
+
+Behavior is defined by [the locale tables](https://github.com/corbet-labs/cink/tree/main/tables)
+and [shared conformance vectors](https://github.com/corbet-labs/cink/tree/main/tests/vectors).
+Rust, JavaScript, and Python run the same vectors. Selected CI checks exercise
+installed JavaScript tarballs, Python wheels and command-line entrypoints, and
+Typst packages. Release validation records the actual runtime and platform;
+Linux results do not establish native Windows or macOS coverage.
+All five Rust crates forbid unsafe code in their own source.
+
+See [the release guide](https://github.com/corbet-labs/cink/blob/main/docs/releasing.md)
+for generation, verification, and publication commands.
+
+## License
+
+Copyright 2026 Julian Y. Richard Corbet. cink 0.1.4 is licensed under [Apache-2.0](https://github.com/corbet-labs/cink/blob/main/LICENSES/Apache-2.0.txt). Previously published versions retain their original license grants.

cink-0.1.4/cink/__init__.py

@@ -0,0 +1,150 @@
+"""Validate and size handwritten signature images for correspondence."""
+
+import base64
+import binascii
+import math
+import struct
+from dataclasses import dataclass
+from typing import Literal
+
+from ._tables import TABLES
+
+_DEFAULTS = TABLES["defaults"]
+_PNG = b"\x89PNG\r\n\x1a\n"
+_SOF = {0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf}
+__all__ = ["default_max_pixels", "supported_formats", "normalize", "exceeds_limits",
+           "scale_to_fit", "signature_size", "image_snippet"]
+
+
+@dataclass(frozen=True)
+class DecodedImage:
+    """Image format, optional raster dimensions, and original encoded bytes."""
+
+    mime: Literal["png", "jpeg", "svg"]
+    width: int | None
+    height: int | None
+    bytes: bytes
+
+
+def default_max_pixels() -> int:
+    """Default raster pixel budget."""
+    return _DEFAULTS["max_pixels"]
+
+
+def supported_formats() -> list[str]:
+    """Accepted image formats."""
+    return sorted(_DEFAULTS["formats"])
+
+
+def _jpeg_dimensions(data: bytes) -> tuple[int, int] | None:
+    pos = 2
+    while pos < len(data):
+        if data[pos] != 0xff:
+            return None
+        while pos < len(data) and data[pos] == 0xff:
+            pos += 1
+        if pos >= len(data):
+            return None
+        marker = data[pos]
+        pos += 1
+        if marker == 1:
+            continue
+        if marker == 0 or 0xd0 <= marker <= 0xda:
+            return None
+        if pos + 2 > len(data):
+            return None
+        length = struct.unpack_from(">H", data, pos)[0]
+        if length < 2 or length > len(data) - pos:
+            return None
+        if marker in _SOF:
+            if length < 8:
+                return None
+            components = data[pos + 7]
+            if not components or length != 8 + 3 * components:
+                return None
+            height, width = struct.unpack_from(">HH", data, pos + 3)
+            return (width, height) if width and height else None
+        pos += length
+    return None
+
+
+def normalize(value: str) -> DecodedImage | None:
+    """Read PNG/JPEG headers or pass SVG through from canonical base64/a data URL.
+
+    Required padding must be present; whitespace and nonzero unused bits are rejected.
+    Header recognition does not fully decode a raster or sanitize SVG markup.
+    """
+    payload = value
+    if value.startswith("data:") and "," in value:
+        meta, payload = value.split(",", 1)
+        if not meta.endswith(";base64"):
+            return None
+    if not payload:
+        return None
+    try:
+        data = base64.b64decode(payload, validate=True)
+        if base64.b64encode(data).decode("ascii") != payload:
+            return None
+    except (ValueError, binascii.Error):
+        return None
+    if data.startswith(_PNG):
+        if len(data) < 33 or data[8:16] != b"\x00\x00\x00\x0dIHDR":
+            return None
+        width, height = struct.unpack_from(">II", data, 16)
+        if not 0 < width <= 0x7fffffff or not 0 < height <= 0x7fffffff:
+            return None
+        depth, color, compression, filtering, interlace = data[24:29]
+        valid_depths = {0: (1, 2, 4, 8, 16), 2: (8, 16), 3: (1, 2, 4, 8), 4: (8, 16), 6: (8, 16)}
+        if depth not in valid_depths.get(color, ()) or compression != 0 or filtering != 0 or interlace > 1:
+            return None
+        return DecodedImage("png", width, height, data)
+    if data.startswith(b"\xff\xd8"):
+        dims = _jpeg_dimensions(data)
+        return DecodedImage("jpeg", *dims, data) if dims else None
+    if data.lstrip(b" \t\n\r\f").startswith(b"<svg"):
+        return DecodedImage("svg", None, None, data)
+    return None
+
+
+def exceeds_limits(image: DecodedImage, max_pixels: int) -> bool:
+    """Whether raster dimensions exceed a pixel budget."""
+    return image.width is not None and image.height is not None and image.width * image.height > max_pixels
+
+
+def scale_to_fit(image: DecodedImage, max_pixels: int) -> float:
+    """Scale factor at most one; callers perform any resampling."""
+    if image.width is None or image.height is None or not exceeds_limits(image, max_pixels):
+        return 1.0
+    return math.sqrt(max_pixels / (image.width * image.height))
+
+
+def signature_size(image: DecodedImage, height_pt: float, max_width_pt: float | None = None) -> tuple[float, float] | None:
+    """Aspect-preserving point size, or None for invalid/nonrepresentable sizes."""
+    if (type(image.width) is not int or type(image.height) is not int
+            or not 0 < image.width <= 0xffffffff or not 0 < image.height <= 0xffffffff
+            or type(height_pt) not in (int, float)
+            or (max_width_pt is not None and type(max_width_pt) not in (int, float))):
+        return None
+    try:
+        height_pt = float(height_pt)
+        if max_width_pt is not None:
+            max_width_pt = float(max_width_pt)
+    except OverflowError:
+        return None
+    if (not math.isfinite(height_pt) or height_pt <= 0
+            or (max_width_pt is not None and (not math.isfinite(max_width_pt) or max_width_pt <= 0))):
+        return None
+    ratio = image.width / image.height
+    width = height_pt * ratio
+    if max_width_pt is not None and width > max_width_pt:
+        width, height_pt = max_width_pt, max_width_pt / ratio
+    return (width, height_pt) if math.isfinite(width) and math.isfinite(height_pt) and width > 0 and height_pt > 0 else None
+
+
+def image_snippet(path: str, height_pt: float, width_pt: float | None = None) -> str:
+    """A Typst image call; placement remains the caller's responsibility."""
+    escapes = {'"': '\\"', "\\": "\\\\", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+    safe = "".join(escapes.get(char, f"\\u{{{ord(char):x}}}" if ord(char) < 32 or 127 <= ord(char) <= 159 else char) for char in path)
+    height = format(height_pt, ".15g")
+    width = "" if width_pt is None else f", width: {format(width_pt, '.15g')}pt"
+    return f'#image("{safe}", height: {height}pt{width})'

cink-0.1.4/cink/__main__.py

@@ -0,0 +1,50 @@
+"""JSON command-line bridge for callers in any programming language."""
+import argparse
+import base64
+import dataclasses
+import json
+import sys
+import cink as api
+
+
+def _json_default(value):
+    if dataclasses.is_dataclass(value):
+        return dataclasses.asdict(value)
+    if isinstance(value, bytes):
+        return base64.b64encode(value).decode("ascii")
+    raise TypeError(f"Cannot serialize {type(value).__name__}")
+
+
+def _reject_constant(value):
+    raise ValueError(f"{value} is not a JSON number")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Call cink functions with JSON arguments.")
+    parser.add_argument("function", choices=api.__all__)
+    parser.add_argument("arguments", nargs="?", default="[]", help="JSON array of positional arguments or object of keyword arguments; '-' reads UTF-8 stdin")
+    args = parser.parse_args()
+    try:
+        values = json.loads(sys.stdin.buffer.read().decode("utf-8") if args.arguments == "-" else args.arguments, parse_constant=_reject_constant)
+        if not isinstance(values, (list, dict)):
+            raise ValueError("arguments must be a JSON array or object")
+        # Image operations accept the JSON object returned by normalize.
+        if args.function in ("exceeds_limits", "scale_to_fit", "signature_size"):
+            raw = values[0] if isinstance(values, list) else values["image"]
+            if isinstance(raw, dict):
+                raw = dict(raw)
+                raw["bytes"] = base64.b64decode(raw["bytes"], validate=True)
+                image = api.DecodedImage(**raw)
+                if isinstance(values, list):
+                    values[0] = image
+                else:
+                    values["image"] = image
+        fn = getattr(api, args.function)
+        result = fn(*values) if isinstance(values, list) else fn(**values)
+        print(json.dumps(result, default=_json_default, ensure_ascii=True, allow_nan=False))
+    except (ValueError, TypeError, KeyError, IndexError, AttributeError, OverflowError) as error:
+        parser.error(str(error))
+
+
+if __name__ == "__main__":
+    main()

cink-0.1.4/cink/_tables.py

@@ -0,0 +1,2 @@
+# Generated by scripts/sync-python.py; edit tables/*.json instead.
+TABLES = {'defaults': {'max_pixels': 1600, 'formats': ['png', 'jpeg', 'svg']}}

cink-0.1.4/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cink"
+version = "0.1.4"
+description = "Handwritten signature image rendering for correspondence. Pixels, not signatures"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSES/*"]
+requires-python = ">=3.10"
+keywords = ["i18n", "correspondence", "locale"]
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent"]
+
+
+[project.urls]
+Homepage = "https://github.com/corbet-labs/cink#readme"
+Repository = "https://github.com/corbet-labs/cink"
+Issues = "https://github.com/corbet-labs/cink/issues"
+
+[project.scripts]
+cink = "cink.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cink"]

cink-0.1.4/scripts/conformance.py

@@ -0,0 +1,64 @@
+"""Run canonical vectors against either the source port or an installed wheel."""
+import base64
+import importlib
+import json
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[2]
+if "--installed" not in sys.argv:
+    sys.path.insert(0, str(ROOT / "py"))
+api = importlib.import_module("cink")
+
+ARGUMENTS = {
+    "region_parse": ["input"], "region_uses_comma": ["input"],
+    "salutation_last_name": ["input"], "salutation_honorific": ["input"],
+    "salutation_titles": ["input"], "salutation_surname": ["input"],
+    "de_salutation": ["input", "region"],
+    "recipient_salutation_warning": ["location", "input"],
+    "de_honorific_warning": ["location", "input"],
+    "closing": ["locale", "override"], "available_locales": [],
+    "long_date": ["locale", "year", "month", "day"],
+    "medium_date": ["locale", "year", "month", "day"],
+    "short_date": ["locale", "year", "month", "day"],
+    "month_year": ["locale", "year", "month"], "is_supported": ["locale"],
+    "supported_formats": [], "normalize": ["input"],
+    "exceeds_limits": ["image", "max_pixels"], "scale_to_fit": ["image", "max_pixels"],
+    "signature_size": ["image", "height_pt", "max_width_pt"],
+    "image_snippet": ["path", "height_pt", "width_pt"],
+    "resolve_locale": ["language", "location"],
+    "opening": ["locale", "person", "override"],
+    "subject": ["locale", "title", "prefix_override"],
+    "salutation": ["locale", "person"], "apply_ortho": ["locale", "text"],
+    "warnings": ["location", "locale", "person"],
+}
+
+files = sorted((ROOT / "tests/vectors").glob("*.json"))
+assert files, "No conformance vectors"
+count = 0
+for file in files:
+    for vector in json.loads(file.read_text(encoding="utf-8")):
+        name = vector["fn"]
+        values = dict(vector)
+        if "fixture" in vector:
+            values["input"] = base64.b64encode((ROOT / "tests/fixtures" / vector["fixture"]).read_bytes()).decode("ascii")
+            if name != "normalize":
+                values["image"] = api.normalize(values["input"])
+        fn = getattr(api, "parse_region" if name == "region_parse" else name)
+        actual = fn(*(values.get(key) for key in ARGUMENTS[name]))
+        if name == "normalize" and actual is not None:
+            actual = {key: getattr(actual, key) for key in ("mime", "width", "height")}
+        if isinstance(actual, tuple):
+            actual = list(actual)
+        if actual != vector["expected"]:
+            raise AssertionError(f"{file.name} :: {vector['name']}: {actual!r} != {vector['expected']!r}")
+        count += 1
+image = api.DecodedImage("png", 1, 1, b"")
+for invalid in (float("nan"), float("inf"), -float("inf"), 0, -1, True, 10**400):
+    assert api.signature_size(image, invalid) is None
+    assert api.signature_size(image, 20, invalid) is None
+for invalid_dimension in (0, -1, 1.5, True, 0x100000000):
+    assert api.signature_size(api.DecodedImage("png", invalid_dimension, 1, b""), 20) is None
+assert api.signature_size(api.DecodedImage("png", 2, 1, b""), sys.float_info.max, 30) == (30, 15)
+assert api.signature_size(api.DecodedImage("png", 1, 2, b""), float.fromhex("0x0.0000000000001p-1022")) is None
+print(f"Python cink: {count} vectors across {len(files)} files and numeric boundary checks passed")

cink-0.1.4/scripts/consumer.py

@@ -0,0 +1,106 @@
+"""Verify wheel/sdist contents and installed Python/console entrypoints.
+
+Run with the interpreter in a fresh environment containing the wheel and its
+declared dependencies. This script never adds the source package to sys.path.
+"""
+import argparse
+import base64
+from email.parser import BytesParser
+import importlib
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tarfile
+import tempfile
+import zipfile
+
+ROOT = Path(__file__).resolve().parents[2]
+PACKAGES = [path.name for path in (ROOT / "py").iterdir() if (path / "__init__.py").is_file()]
+if len(PACKAGES) != 1:
+    raise RuntimeError("Expected exactly one source package")
+NAME = PACKAGES[0]
+CASES = {
+    "cgreet": ("de_salutation", ["Frau Dr. Müller", "ch"],
+               {"name": "Frau Dr. Müller", "region": "ch"}, "Sehr geehrte Frau Dr. Müller"),
+    "cfarewell": ("closing", ["DE-LI"], {"locale": "DE-LI"}, "Freundliche Grüsse"),
+    "cdate": ("long_date", ["EN-GB", 2026, 9, 7],
+              {"locale": "EN-GB", "year": 2026, "month": 9, "day": 7}, "7 September 2026"),
+    "cink": ("image_snippet", ["signature.png", 20],
+             {"path": "signature.png", "height_pt": 20}, '#image("signature.png", height: 20pt)'),
+    "cletter": ("salutation", ["DE-LI", "Frau Dr. Müller"],
+                {"locale": "DE-LI", "name": "Frau Dr. Müller"}, "Sehr geehrte Frau Dr. Müller"),
+}
+
+
+def check(condition, message):
+    if not condition:
+        raise AssertionError(message)
+
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument("--wheel", type=Path, required=True)
+parser.add_argument("--sdist", type=Path, required=True)
+args = parser.parse_args()
+licenses = {path.name: path.read_bytes() for path in (ROOT / "LICENSES").iterdir() if path.is_file()}
+check(bool(licenses), "Source licenses are missing")
+with zipfile.ZipFile(args.wheel) as wheel:
+    files = wheel.namelist()
+    check(f"{NAME}/py.typed" in files, "Wheel is missing py.typed")
+    metadata_paths = [path for path in files if path.endswith(".dist-info/METADATA")]
+    check(len(metadata_paths) == 1, "Expected one wheel distribution")
+    metadata = BytesParser().parsebytes(wheel.read(metadata_paths[0]))
+    check(metadata["Name"] == NAME, "Wheel package name differs from repository")
+    expected_license = json.loads((ROOT / "js" / "@corbet-labs" / NAME / "package.json").read_text())["license"]
+    check(metadata["License-Expression"] == expected_license, "Wheel license differs from repository")
+    for name, expected in licenses.items():
+        check(any(path.endswith("/LICENSES/" + name) and wheel.read(path) == expected for path in files),
+              f"Wheel is missing the original {name}")
+with tarfile.open(args.sdist, "r:gz") as sdist:
+    files = {member.name: member for member in sdist.getmembers() if member.isfile()}
+    for name, expected in licenses.items():
+        check(any(path.endswith("/LICENSES/" + name) and sdist.extractfile(member).read() == expected
+                  for path, member in files.items()), f"Source distribution is missing {name}")
+
+distribution = importlib.metadata.distribution(NAME)
+check(distribution.version == metadata["Version"], "Installed version differs from wheel")
+check(any(entry.group == "console_scripts" and entry.name == NAME and entry.value == f"{NAME}.__main__:main"
+          for entry in distribution.entry_points), "Missing console entrypoint metadata")
+api = importlib.import_module(NAME)
+check(not Path(api.__file__).resolve().is_relative_to(ROOT / "py"), "Imported source tree instead of installed wheel")
+entrypoint = Path(sys.executable).parent / (NAME + (".exe" if os.name == "nt" else ""))
+check(entrypoint.is_file(), "Installer did not create the console entrypoint")
+function, positional, keywords, expected = CASES[NAME]
+
+with tempfile.TemporaryDirectory(prefix=f"{NAME}-python-consumer-") as cwd:
+    def call(command, function, values, *, stdin=False, valid=True):
+        payload = values if isinstance(values, str) else json.dumps(values, ensure_ascii=False)
+        result = subprocess.run(command + [function, "-" if stdin else payload],
+                                input=payload if stdin else None, cwd=cwd, text=True,
+                                encoding="utf-8", capture_output=True, timeout=30)
+        if valid:
+            check(result.returncode == 0, result.stderr)
+            return json.loads(result.stdout)
+        check(result.returncode == 2 and not result.stdout and "Traceback" not in result.stderr,
+              f"Invalid arguments did not produce a clean CLI error: {result}")
+
+    for command in ([sys.executable, "-m", NAME], [str(entrypoint)]):
+        check(call(command, function, positional) == expected, "Positional JSON invocation failed")
+        check(call(command, function, keywords, stdin=True) == expected, "Keyword/stdin invocation failed")
+        call(command, function, "null", valid=False)
+        call(command, function, "[NaN]", valid=False)
+        call(command, function, [], valid=False)
+    if NAME in ("cink", "cletter"):
+        encoded = base64.b64encode(b'<svg xmlns="http://www.w3.org/2000/svg"/>').decode("ascii")
+        decoded = call([str(entrypoint)], "normalize", [encoded])
+        check(decoded["bytes"] == encoded and decoded["mime"] == "svg", "Image JSON output lost encoded bytes")
+        check(call([str(entrypoint)], "signature_size", {"image": decoded, "height_pt": 20}) is None,
+              "Image JSON output cannot be used as a subsequent input")
+        raster = {"mime": "png", "width": 1, "height": 1, "bytes": ""}
+        check(call([str(entrypoint)], "signature_size", {"image": raster, "height_pt": 10**400}) is None,
+              "An unrepresentable height escaped the JSON bridge")
+        check(call([str(entrypoint)], "signature_size", {"image": raster, "height_pt": 20, "max_width_pt": 10**400}) is None,
+              "An unrepresentable maximum width escaped the JSON bridge")
+print(f"Python {NAME}: installed module, console JSON calls, wheel/sdist licenses and metadata passed")