@tileflow/dev 0.1.0-alpha.3 → 0.1.0-alpha.31

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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.

package/README.md

@@ -1,13 +1,209 @@
 # @tileflow/dev
 
-Node utilities used by the Tileflow CLI and build integrations.
+Node.js utilities for custom Tileflow build tools and development servers. Load a trusted
+`tileflow.config.ts`, prepare its assets, and produce a validated artifact generation.
+
+Most applications should use the [CLI](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md)
+or the [Vite](https://github.com/tileflow/tileflow-sdk/blob/main/packages/vite/README.md),
+[Next.js](https://github.com/tileflow/tileflow-sdk/blob/main/packages/next/README.md), or
+[Webpack](https://github.com/tileflow/tileflow-sdk/blob/main/packages/webpack/README.md) integration.
+This package is for implementing an integration, not for browser rendering.
+
+> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
+
+## Install
+
+Use Node.js 22 or newer:
+
+```sh
+npm install --save-dev @tileflow/dev@alpha @tileflow/core@alpha @tileflow/maps@alpha
+```
+
+Create a trusted `tileflow.config.ts` in the working directory:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({id: 'madrid', version: 1, extends: streets});
+```
+
+Loading the config executes its imports. It is not a sandbox for untrusted code. Local preparation
+needs no API key, but serving a map can still cause requests to its remote data or font providers.
+
+## Prepare a generation
+
+<!-- docs:check -->
 
 ```ts
-import { createTileflowBuildArtifacts } from "@tileflow/dev";
+import {createTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
+
+const artifacts = await createTileflowBuildArtifacts({config: 'tileflow.config.ts'});
+
+try {
+  console.log(artifacts.manifest);
+  console.log(Object.keys(artifacts.styles.madrid));
+} finally {
+  await artifacts.dispose?.();
+}
+```
+
+The artifact plan exposes files and observed inputs from the same generation. Styles are keyed as
+`styles[map][theme]`, never as an implicit default-theme alias. Keep that generation alive for the
+whole operation, then release it. Do not reconstruct its asset list from directory guesses.
+
+To write production output rather than manage it in memory:
 
-const artifacts = await createTileflowBuildArtifacts({
-  config: "tileflow.config.ts",
+<!-- docs:check -->
+
+```ts
+import {writeTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
+
+await writeTileflowBuildArtifacts({
+  config: 'tileflow.config.ts',
+  outDir: 'public/tileflow',
 });
 ```
 
-Docs: https://tileflow.dev/docs
+Serve the complete output. The writer installs immutable generation assets before changing the
+manifest pointer, tracks its own files, and refuses to replace a hosted manifest by default.
+`overwriteHostedManifest: true` is an explicit migration option, not a normal build setting.
+Production rejects unresolved local PMTiles; publish data explicitly or provide an application-owned
+production source. Local development snapshots do not publish or redistribute the original dataset.
+
+Maps whose labels use a line-fitted `text.background` draw text with derived glyph stacks. Local
+previews and captures route such a map's glyph URL through `__glyphs/<map>/…`. Ordinary stacks pass
+through from the declared provider; derived ranges are computed from their source ranges, which are
+cached under `.tileflow/cache/glyphs/v1`. Production output keeps the declared provider, which must
+serve derived stacks.
+
+## Keep a watched request handler
+
+Use one session for repeated work and close it when the owning server stops:
+
+<!-- docs:check -->
+
+```ts
+import {createTileflowArtifactSession} from '@tileflow/dev/artifacts';
+import {createTileflowDevRequestHandler} from '@tileflow/dev/server';
+
+export async function createMapHandler() {
+  const session = await createTileflowArtifactSession({
+    config: 'tileflow.config.ts',
+    watch: true,
+  });
+  const handler = createTileflowDevRequestHandler({session});
+
+  return {
+    fetch: handler,
+    async close() {
+      await handler.close();
+      await session.close();
+    },
+  };
+}
+```
+
+The caller mounts `fetch` in its server and calls `close()` on shutdown. This factory does not open
+a listener. Sessions follow config imports and local asset inputs, retain the last good generation
+after invalid edits, and publish structured state changes through `subscribe()`.
+Watching follows aliased working directories, including newly created or removed icon metadata.
+A single startup consistency check complements ordinary watcher notifications; no recurring scan
+is added.
+
+`getState()` and `getLastGoodArtifacts()` return borrowed synchronous views. Before asynchronous
+work, call `acquireArtifacts(generation?)` and release the acquisition in `finally`. A replaced
+generation accepts no new acquisitions; closing a session waits for existing acquisitions.
+
+## Choose an entry point
+
+Use `/artifacts` for preparation and output, `/server` for HTTP handling, `/config` for trusted config
+loading, `/icons` and `/fonts` for asset preparation, `/inspect` for bounded inspection, `/tilesets`
+for local PMTiles inspection, and `/validation` for diagnostics. `/preview` is the local preview
+contract, including experimental preview-only rendering; it does not promise hosted support.
+The package has no root entry point.
+
+Invalid compiled styles throw `TileflowStyleValidationError` with bounded issues. Keep diagnostics
+structured; do not return executable config, local paths, credentials, or complete generated byte
+arrays from a public endpoint.
+
+## Locked Icon Set composition
+
+`composeTileflowIconSources(sources, {cwd, lock, cacheRoot, offline: true})` combines local/package
+directories and `iconSet('@team/set')` contributors into one effective sprite. Without an explicit
+lock object, it reads `tileflow.icons.lock.json` beside `baseDirectory` (default: `cwd`). It never
+resolves latest or writes the lock. The result contains the generated `package`, ordered
+`composition` receipt, effective `sourceIdentities`, declared `contributors`, effective `winners`,
+replacement ordinals, local `watchPaths`, and the exact `watchFiles` that select the composition.
+Pass both the source identities and receipt to Core map-revision hashing.
+
+This is the one normal icon-preparation path. `compileTileflowIconPackages`,
+`prepareTileflowCatalogIcons`, `inspectTileflowIconCatalogs` and `getTileflowIconWatchPaths` all use
+it, so `createTileflowBuildArtifacts`, `createTileflowArtifactSession`, and every adapter that
+enters them accept the same explicit `icons` resolution options: `cacheRoot`, `offline`,
+`deliveryOrigins`, `fetch` and `signal`. An explicit `cacheRoot` takes precedence over
+`TILEFLOW_ICON_CACHE_DIR`, then the OS cache default. Origins and transport use their documented
+defaults unless supplied explicitly; no build or watch polls a catalog head. `prepareTileflowCatalogIcons`
+returns `mapIconCompositions` alongside `mapIconSources`, and build-manifest entries carry the
+receipt as `sourceAssets.iconComposition` with `mapRevisionSchemaVersion: 2`.
+
+A map whose contributors are all local or package directories keeps its existing generated bytes,
+manifest and content hash, and its build-manifest entry stays on the legacy v1 contract.
+
+The reader verifies each file length/checksum, PNG/index geometry, names, density pairing, and both
+per-icon pixel hashes. It copies decoded 1x and 2x cells independently, without resampling either.
+The existing directory compiler and this port share the same sprite packer. A sole shared set reuses
+its exact artifact; mixed inputs are packed deterministically. Later contributors win and all
+dependencies remain in the receipt, even when entirely shadowed. Shared inputs never pretend to
+contain original SVG/source identities. Existing local-only compilation remains unchanged.
+
+`storeTileflowIconSetArtifact` seeds an exact verified cache entry. `loadTileflowIconSetArtifact`
+uses the cache or hydrates only the selected artifact's four public files. Hydration defaults to the
+trusted `https://api.tileflow.dev` origin, sends no credentials, and follows no redirects.
+Applications may explicitly configure trusted `deliveryOrigins`; locks cannot add them. `offline`
+forbids all fetches and fails on missing or corrupt entries. Complete-map offline rendering still
+depends on unrelated tiles, glyphs, and other external resources.
+
+The cache lives under the OS user cache with `tileflow/icons/v1/<contentHash>`. `cacheRoot`, then
+`TILEFLOW_ICON_CACHE_DIR`, overrides its parent. Atomic directory installation and exact-entry
+retirement support concurrent writers and corruption repair. Symlink entries are rejected. This is
+a disposable cache, not a security sandbox against another process controlling the same user
+account. Incomplete temporary entries are never accepted as published cache entries.
+
+`readTileflowIconsLockfileText(directory)` returns the exact current lock bytes, or `null` when no
+lock exists; those bytes are the only valid `expectedContents` for the next write.
+`writeTileflowIconsLockfile(directory, lock, expectedContents)` uses a whole-file compare-and-swap
+and atomic rename. A conflicting writer fails without overwriting pins. An interrupted writer leaves
+the previous complete lock intact; remove a stale `.writing` guard only after confirming that its
+writer has exited. Ordinary reads and Core validation never acquire write guards.
+
+A package supports up to 1,000 effective icons, subject to a 2,048-pixel atlas dimension,
+4 MiB per generated file, and 8 MiB per package. Paired densities share a logical layout capped
+at 1,024 pixels per dimension at 1× and 2,048 at 2×. Mixed-size artwork retains matching placements
+without resampling either density. Larger artwork can hit those limits before
+1,000 icons. Several individually valid sets can exceed the effective map limit; composition
+fails explicitly instead of clipping. Cache and composition do not create Team resources or
+publish anything. Every normal entry point composes declared shared descriptors through this path;
+catalog publication and lock maintenance stay in the `tileflow` CLI, which is the only writer of
+`tileflow.icons.lock.json` and the only caller that resolves `latest`.
+
+## Detailed guides
+
+These references are also included under `docs/` in the installed package:
+
+- [Native artifact preparation](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md): static compatibility, renderer-qualified output, and limitations.
+- [Artifact lifecycle](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/artifact-lifecycle.md): generations, immutable snapshots, provenance, and cleanup.
+- [Local comparison and inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/local-comparison-workbench-and-compiler-inspection.md): workbench controls and preview-only models.
+- [Config diagnostics](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/structured-config-inspection-and-diagnostics.md): bounded, machine-readable inspection.
+- [PMTiles inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/bounded-pmtiles-resource-inspection.md): metadata, sampling limits, and requested properties.
+- [Feature and icon inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/bounded-vector-feature-inspection.md): supported sources, icon compilation, and delivered-pixel hashes.
+
+For an installed release, prefer its declarations and packaged guides over newer source on `main`.
+
+## Recolorable icons
+
+Declare SDF defaults and optional stretch/content layout in `tileflow.icons.json` beside ordinary artwork. Preparation
+verifies both densities and rejects mixed representations within one symbol layer, including
+fallbacks and local overrides. See [Author recolorable and adaptable icons](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-icons.md) for the input profile, diagnostics and recovery.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,87 @@
+# Third-party notices
+
+This file records third-party components used by Node preparation and preview. Official map artwork
+and fonts are owned and published by `@tileflow/maps`; `@tileflow/dev` does not carry an `assets/`
+directory. Runtime dependencies are installed as separate npm packages, and their code and native
+binaries are not copied into the dev package.
+
+## Bitmap distance transform
+
+`src/icon-distance.ts` adapts the alpha distance transform from bitmap-sdf 1.0.4 for bounded,
+Node-only sprite preparation. The adaptation removes browser globals and adds input validation.
+Source: <https://github.com/dy/bitmap-sdf>. License: MIT.
+
+Copyright 2020 Dmitry Ivanov
+
+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-owned map fonts
+
+The generic font preparation pipeline reads map-owned TTF, OTF, and WOFF2 directories; it does not
+embed fonts in `@tileflow/dev`. Each source directory must carry its own `LICENSE.txt`, which is
+copied into the deterministic build artifacts whenever that directory contributes a selected face.
+
+The source repository's generic font tests retain pinned Oxanium fixtures and their complete
+SIL Open Font License 1.1 notice under `test/fixtures/fonts/oxanium/`. These fixtures are not
+included in the published package. Community map fonts are owned by
+[Community Maps](https://github.com/tileflow/community-maps).
+
+## fontkit 2.0.4
+
+Font metadata for TTF, OTF, and WOFF2 inputs is read with the separately installed `fontkit`
+package. fontkit is copyright Devon Govett and contributors and is distributed under the MIT
+License.
+
+- Source: <https://github.com/foliojs/fontkit/tree/v2.0.4>
+- License: <https://github.com/foliojs/fontkit/blob/v2.0.4/LICENSE>
+
+## PMTiles JavaScript 4.5.0
+
+The local Streets preview loads the separately installed `pmtiles` browser decoder to retrieve
+individual landmark GLB entries with HTTP byte ranges. PMTiles is copyright Protomaps and
+contributors and is distributed under the BSD 3-Clause License. Its `fflate` dependency is
+copyright 2020 Arjun Barrett and is distributed under the MIT License.
+
+- PMTiles source and license: <https://github.com/protomaps/PMTiles/tree/v4.5.0/js>
+- fflate source and license: <https://github.com/101arrowz/fflate/tree/v0.8.3>
+
+## sharp 0.35.5
+
+`@tileflow/dev` declares `sharp` as an optional dependency and loads it dynamically only when local
+SVG or raster icon sources must be inspected and packed. The Tileflow build externalizes `sharp`
+rather than bundling it. `sharp` is copyright Lovell Fuller and contributors and is distributed under
+the Apache License 2.0.
+
+- Source: <https://github.com/lovell/sharp/tree/v0.35.5>
+- License: <https://github.com/lovell/sharp/blob/v0.35.5/LICENSE>
+
+## sharp libvips distributions 1.3.4
+
+`sharp` selects a separate optional `@img/sharp-libvips-*` package for the current platform. The
+installed platform-package manifest declares `LGPL-3.0-or-later`; the packaging scripts themselves
+are distributed under Apache-2.0. The packages contain prebuilt libvips and separately licensed
+runtime dependencies. For `sharp` 0.35.5 the selected libvips ABI is 8.18.7.
+
+- Packaging source: <https://github.com/lovell/sharp-libvips/tree/v1.3.4>
+- Packaging-script license: <https://github.com/lovell/sharp-libvips/blob/v1.3.4/LICENSE>
+- libvips 8.18.7 source: <https://github.com/libvips/libvips/tree/v8.18.7>
+- libvips 8.18.7 license (LGPL-2.1-or-later):
+  <https://github.com/libvips/libvips/blob/v8.18.7/LICENSE>
+
+Because `sharp` remains a separately installed optional package, users can install, update, remove,
+or replace it independently of `@tileflow/dev`. Tileflow does not modify libvips and does not place a
+libvips shared library or a `sharp` native addon inside any Tileflow package tarball. Release smoke
+tests enforce that package boundary.