@tileflow/static 0.1.0-alpha.3 → 0.1.0-alpha.30

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,20 +1,299 @@
 # @tileflow/static
 
-Static map schemas, overlay helpers, and request utilities for Tileflow static map rendering.
+Validate static map scenes, author overlays, and request hosted image renders. The client follows
+an asynchronous operation until an immutable image is ready. It does not display the image or
+provide an interactive map.
+
+> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
+
+## Install
+
+```sh
+npm install @tileflow/static@alpha
+```
+
+Validation and overlay authoring work without a hosted account. Creating a render needs a deployed
+Tileflow map, an enabled Static Maps service, and an authorized credential. Run authenticated
+requests on a trusted server with `fetch` available, such as Node.js 22 or newer. Keep credentials
+out of browser bundles. A React application can use
+[`@tileflow/react/static`](https://github.com/tileflow/tileflow-sdk/blob/main/packages/react/README.md)
+through its own authorized server endpoint.
+
+## Create a render
+
+Every scene names one concrete `theme`. The browser-only `"system"` selector is rejected so hashes,
+cache keys, receipts, and regenerated images remain reproducible.
+
+Scene, size, camera, attribution, padding, and overlay objects are strict. Unknown fields are
+rejected instead of being removed during normalization, so misspelled or unsupported options cannot
+silently share another scene's identity.
+
+<!-- docs:check -->
 
 ```ts
-import {marker, precacheStaticMap, validateStaticScene} from '@tileflow/static';
+import {createStaticMap, createStaticMapIdempotencyKey} from '@tileflow/static/client';
+import {marker} from '@tileflow/static/overlays';
+import {validateStaticScene} from '@tileflow/static/scene';
+
+const apiKey = process.env.TILEFLOW_API_KEY;
+if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
 
 const scene = validateStaticScene({
   map: 'madrid',
-  camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
-  size: {width: 1200, height: 800},
+  theme: 'dark',
+  format: 'webp',
+  camera: {type: 'auto', padding: 24},
+  size: {width: 600, height: 400, dpr: 2},
   overlays: [marker({coordinate: [-3.7038, 40.4168]})],
 });
 
-await precacheStaticMap(scene.scene, {
-  apiKey: process.env.TILEFLOW_API_KEY,
+if (!scene.ok) throw new Error(scene.error);
+
+const idempotencyKey = createStaticMapIdempotencyKey();
+const result = await createStaticMap(scene.scene, {
+  apiKey,
+  idempotencyKey,
+});
+
+console.log(result.imageUrl, result.attribution.entries);
+```
+
+`map: 'madrid'` is the deployed portable map name; replace it with yours. For a Team credential,
+pass the destination's public `mapId` separately in the request options, as described below.
+`createStaticMap` and `precacheStaticMap` both return a hosted result with `resultVersion: 1`, an
+operation ID, image URL, and attribution. Use precache for cache warming, not as a free validation
+operation. Neither helper is the same as `<Map mode="image">`, which only displays an existing image.
+
+Create one idempotency key per intentional action and retain it across retries. Do not put the key
+factory inside a retry callback. The helper handles polling; cancellation or a timeout does not
+prove that the server did no work.
+
+## Image size and format
+
+`width` and `height` are logical CSS pixels. `dpr` accepts 1 or 2 and defaults to 1, so a 600 by
+400 scene at DPR 2 produces a 1200 by 800 image without changing camera, padding, or overlay paint
+sizes. Logical dimensions may reach 2048 per axis; the physical budget permits 4096 by 4096 output,
+or 16,777,216 total pixels.
+
+`format` accepts `png`, `jpeg`, or `webp` and defaults to PNG. PNG's canonical default stays omitted,
+so explicit and omitted PNG requests share identity. JPEG and WebP use a fixed encoder quality;
+there is no public quality option.
+
+## Semantic overlays
+
+Every overlay accepts a semantic `placement`:
+
+- `above-water`
+- `below-roads`
+- `above-roads`
+- `above-buildings`
+- `below-labels`
+- `above-labels` (default)
+
+These values are stable across themes. They never expose a physical Style layer ID. Array order is
+preserved within each placement; later overlays paint above earlier overlays in the same group.
+
+Use `symbol` for a deployed sprite icon, renderer-owned text, or both:
+
+```ts
+import {symbol} from '@tileflow/static/overlays';
+
+symbol({
+  coordinate: [-3.7038, 40.4168],
+  icon: 'store',
+  label: {appearance: 'badge', text: '23'},
+  placement: 'above-labels',
+  anchor: 'bottom',
+  offset: [0, -4],
+  scale: 1,
 });
 ```
 
-Docs: https://tileflow.dev/docs
+`icon` is an ID in the exact managed sprite deployed with the selected Map, never a URL. Hosted
+resolves and binds its dimensions before rendering; an unmanaged sprite or absent ID returns a
+non-retryable structured error. `scale` changes the icon while `label.fontSize` controls text.
+`offset` uses logical CSS pixels and moves the complete symbol after anchoring.
+
+A string label is shorthand for `{appearance: 'plain', text}`. `plain` renders text with a halo;
+`badge` renders text in a rounded container. Both use renderer-owned Noto faces independent of theme
+typography. The accepted baseline is generated from the shipped WOFF2 `cmap` tables and covers
+Latin/Extended, Vietnamese, Greek, Cyrillic, Arabic, Hebrew, Devanagari, Thai, Japanese, Simplified
+and Traditional Chinese, and Korean. Symbols and embedded attribution use exactly that coverage.
+Unsupported glyphs fail with `STATIC_MAP_LABEL_UNSUPPORTED`; Chromium must load the matching bundled
+face. The renderer audits the face Chromium actually used for every run; any system-font glyph fails
+the render.
+
+Appearance objects accept `language: 'ja' | 'zh-Hans' | 'zh-Hant' | 'ko'`. It chooses the preferred
+regional Noto CJK face; glyphs absent there fall through only to other bundled regional faces. It
+does not translate text or select map data. Omission and string shorthand normalize to `zh-Hans`.
+That fallback is deterministic but makes no regional-form promise for Han text whose language was
+omitted. Font family and weight are not public controls. Label position can be `center`, any cardinal
+side, or any diagonal side. With an icon, plain defaults above it and badge defaults above-right;
+label-only symbols default to center.
+
+`anchor` accepts the same nine center/cardinal/diagonal positions. `collision: 'always-visible'` is
+the default: the symbol is never hidden and does not reserve collision space. `avoid-overlap`
+participates in MapLibre's shared symbol collision index, including ordinary Style labels and other
+request symbols. The visually higher layer wins: an `above-labels` request symbol can hide a
+colliding Style label, while a `below-labels` symbol yields to it. Higher semantic placement wins
+across placements; later request order wins within one placement. Style-owned overlap properties
+remain authoritative.
+
+## Attribution
+
+New renders default to `attribution: {mode: 'embedded', position: 'auto'}` without adding that
+omitted default to the normalized scene. Hosted derives notices from the sources referenced by the
+exact selected Style and embeds a safe, compact block. Automatic placement prefers an unobstructed
+corner, then the least interfering corner among declared request overlays. Explicit center and
+bounds cameras never move.
+
+Choose a corner when composition requires it:
+
+<!-- docs:check -->
+
+```ts
+import type {StaticAttributionRequest} from '@tileflow/static/scene';
+
+const attribution = {
+  mode: 'embedded',
+  position: 'bottom-left',
+} satisfies StaticAttributionRequest;
+```
+
+Or request structured external attribution:
+
+<!-- docs:check -->
+
+```ts
+import {createStaticMap, createStaticMapIdempotencyKey} from '@tileflow/static/client';
+
+const apiKey = process.env.TILEFLOW_API_KEY;
+if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
+
+const result = await createStaticMap(
+  {
+    map: 'madrid',
+    theme: 'dark',
+    camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+    size: {width: 600, height: 400},
+    attribution: {mode: 'external'},
+  },
+  {apiKey, idempotencyKey: createStaticMapIdempotencyKey()},
+);
+
+console.log(JSON.stringify({imageUrl: result.imageUrl, entries: result.attribution.entries}));
+```
+
+External mode leaves the image unchanged and returns `position: null`. The caller must retain and
+display every returned entry beside the image. Entries contain bounded plain text, safe HTTP(S)
+links, and `platform-notice` or `team-declared` authority; they never contain source HTML or private
+resource IDs. Embedded results return the resolved corner. Changing mode or requested position
+changes scene and artifact identity.
+
+Embedded attribution uses the same generated multilingual coverage as symbol labels and the fixed
+`zh-Hans` CJK fallback. External attribution contains structured text only and is rendered by the
+caller.
+
+## Automatic framing
+
+`camera.type: 'auto'` fits the complete painted footprint of every declared marker, circle, line,
+polygon, and symbol. Symbol sizing uses the exact deployed icon dimensions plus deterministic label
+measurement, anchor, scale, and offset. It works with Mercator and Globe styles when the geometry
+can be shown. It never clips silently.
+
+```ts
+const camera = {
+  type: 'auto',
+  padding: {top: 24, right: 240, bottom: 24, left: 24},
+  maxZoom: 16,
+  bearing: 0,
+} as const;
+```
+
+Padding uses logical CSS pixels. A number applies to every side; omitted sides in an object are
+zero. Without `padding`, Tileflow uses `min(32, ceil(5% * min(width, height)))`. `maxZoom` defaults
+to 16 and `bearing` to 0. A single position still honors asymmetric padding, so its apparent center
+can move away from the viewport center.
+
+Point-like overlays around ±180° use the shortest longitude interval. Tileflow never reinterprets
+vertices inside a line or polygon: an ambiguous crossing returns an error. Represent a correctly
+cut `MultiLineString` or `MultiPolygon` as several `line` or `polygon` overlays with identical
+styles; auto-fit may move each complete component to an adjacent world copy.
+
+Current overlay primitives use MapLibre's GeoJSON pipeline and require
+`abs(latitude) <= MAX_OVERLAY_LATITUDE` (`85.051129`). Tileflow rejects larger latitudes instead of
+clamping them. A Globe basemap may display polar regions even though these overlay primitives cannot
+yet be drawn there.
+
+## Handle failures
+
+Deterministic request failures return `422`, set `retryable: false`, and preserve a stable code,
+reason, and bounded details. `validateStaticScene` returns that document; request helpers throw
+`StaticMapRequestError` either locally or from the Hosted response. The reasons distinguish an empty
+scene, an ambiguous antimeridian path, an out-of-range overlay latitude, an unsupported label glyph,
+an unavailable managed icon or semantic placement, an oversized composed symbol, an insufficient
+viewport, a Globe visibility conflict, an unresolvable camera, and failed post-fit containment.
+Correct the scene or redeploy the Map as directed; do not retry it unchanged. Unsupported
+attribution grammar or glyphs, excessive attribution, and a block that cannot fit use the same
+non-retryable `422` boundary.
+
+Other bounded Hosted JSON failures throw `StaticMapError`. It preserves HTTP `status` and any safe
+`code`, `requiredPlan`, `retryable`, `requestId`, or `remainingUnits` fields the server supplied;
+absent fields are `null`. `StaticMapRequestError` extends the same class. Malformed, oversized, or
+unsafe remote documents remain generic errors and are never reflected to the caller.
+
+`STATIC_MAPS_PLAN_UNAVAILABLE` is a non-retryable Pro requirement. Its `requiredPlan` is
+`starter-v1`; select a Pro Team or use a non-static fallback. It occurs before a Static Maps
+operation or API-unit charge. A different `403` is a credential or Map-coverage failure.
+
+## API entry points
+
+The package has four deliberately separate entry points:
+
+- `@tileflow/static/scene`, scene validation and normalization: `staticSceneSchema`,
+  `validateStaticScene`, and `normalizeStaticScene`;
+- `@tileflow/static/overlays`, overlay authoring and MapLibre compilation: `line`, `circle`,
+  `marker`, `polygon`, `symbol`, and `compileStaticOverlays`;
+- `@tileflow/static/manifest`, renderer identity: `createRenderManifest`,
+  `validateStaticRenderManifest`, `hashRenderManifest`, and `hashStaticSceneRequest`;
+- `@tileflow/static/client`, bounded Hosted transport: `prepareStaticMapRequest`,
+  `createStaticMap`, `precacheStaticMap`, and `requestStaticMapUntilReady`.
+
+The package has no root entry point.
+
+`StaticRenderManifest` is the single strict immutable input contract between a resolved Hosted style
+and a Static Maps renderer. It binds safe attribution, exact source identity, semantic placement
+anchors, and resolved sprite dimensions. Its top-level `mapId` identifies the resolved destination
+while `scene.map` retains the portable map name supplied by the application. It is unrelated to the
+runtime delivery manifest generated by application build or deploy workflows.
+
+## Operation identity and usage
+
+Create one idempotency key per intentional create/precache action and retain it across network
+retries. Reusing the key with the same normalized scene returns the stored result; reusing it with a
+different scene returns 409. A successful paid operation reports `unitCost: 15`, shared
+`remainingUnits`, its durable `operationId`, cache reuse, hash, and immutable image URL. An
+unbounded Pro service reports `remainingUnits: null`. Creation helpers require the single strict
+result contract, including `resultVersion: 1` and attribution. A live
+equal-hash render may return `202`; the helper polls with the same body/key within its bounded wait.
+`maxWaitMs` is the total client completion budget, including network, response parsing, and polling
+delays; `signal` cancels the same complete operation. The helper aborts in-flight work when either
+boundary is reached. It rejects malformed responses, non-HTTP(S) image URLs, and any change of
+durable operation ID while polling.
+
+Framework adapters can call `prepareStaticMapRequest(scene)` once and pass its result to
+`requestStaticMapUntilReady(request, {createUrl, idempotencyKey, ...})`. The prepared request uses
+the same normalized scene for its `sceneKey` and HTTP body, so equivalent omitted/explicit defaults
+deduplicate consistently without duplicating the polling implementation.
+
+Free cannot initiate Static Maps work. Pro consumes 15 shared API units for each successful
+logical operation, including a distinct-key cache reuse. Downloading an immutable PNG, JPEG, or WebP
+consumes zero units.
+
+## Team credentials
+
+A Team credential can serve multiple Maps. Pass `mapId` in the options to `createStaticMap` or
+`precacheStaticMap`; it must be a Managed Map ID such as `map_1234567890abcdef`. The client sends
+`X-Tileflow-Map-Id` separately from the portable scene. `scene.map` remains the deployed environment
+name. The Hosted API must support unified Team credentials and authorize the selected Map.
+Existing Map-scoped keys remain usable without this option. Keep either key on a trusted server.