@tileflow/static 0.1.0-alpha.25 → 0.1.0-alpha.27

package/README.md

@@ -1,10 +1,25 @@
 # @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.
 
-This package describes and submits a render scene, then follows its asynchronous operation until an
-immutable image is ready. It is distinct from React's `<Map mode="image">`, which only displays an
-existing hosted image and does not create or poll a Static Maps operation.
+> 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.
@@ -13,14 +28,19 @@ Scene, size, camera, attribution, padding, and overlay objects are strict. Unkno
 rejected instead of being removed during normalization, so misspelled or unsupported options cannot
 silently share another scene's identity.
 
+<!-- docs:check -->
+
 ```ts
 import {
+  createStaticMap,
   createStaticMapIdempotencyKey,
   marker,
-  precacheStaticMap,
   validateStaticScene,
 } from '@tileflow/static';
 
+const apiKey = process.env.TILEFLOW_API_KEY;
+if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
+
 const scene = validateStaticScene({
   map: 'madrid',
   theme: 'dark',
@@ -32,14 +52,27 @@ const scene = validateStaticScene({
 
 if (!scene.ok) throw new Error(scene.error);
 
-const result = await precacheStaticMap(scene.scene, {
-  apiKey: process.env.TILEFLOW_API_KEY,
-  idempotencyKey: createStaticMapIdempotencyKey(),
+const idempotencyKey = createStaticMapIdempotencyKey();
+const result = await createStaticMap(scene.scene, {
+  apiKey,
+  idempotencyKey,
 });
 
-console.log(result.attribution.entries);
+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,
@@ -119,24 +152,39 @@ bounds cameras never move.
 
 Choose a corner when composition requires it:
 
+<!-- docs:check -->
+
 ```ts
-attribution: {mode: 'embedded', position: 'bottom-left'}
+import type {StaticAttributionRequest} from '@tileflow/static';
+
+const attribution = {
+  mode: 'embedded',
+  position: 'bottom-left',
+} satisfies StaticAttributionRequest;
 ```
 
 Or request structured external attribution:
 
+<!-- docs:check -->
+
 ```ts
+import {createStaticMap, createStaticMapIdempotencyKey} from '@tileflow/static';
+
+const apiKey = process.env.TILEFLOW_API_KEY;
+if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
+
 const result = await createStaticMap(
-  {...scene.scene, attribution: {mode: 'external'}},
   {
-    apiKey: process.env.TILEFLOW_API_KEY,
-    idempotencyKey: createStaticMapIdempotencyKey(),
+    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()},
 );
 
-for (const entry of result.attribution.entries) {
-  renderAttributionText(entry.text, entry.links);
-}
+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
@@ -157,12 +205,12 @@ measurement, anchor, scale, and offset. It works with Mercator and Globe styles
 can be shown. It never clips silently.
 
 ```ts
-camera: {
+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
@@ -180,6 +228,8 @@ Current overlay primitives use MapLibre's GeoJSON pipeline and require
 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
@@ -191,9 +241,15 @@ attribution grammar or glyphs, excessive attribution, and a block that cannot fi
 non-retryable `422` boundary.
 
 Other bounded Hosted JSON failures throw `StaticMapError`. It preserves HTTP `status` and any safe
-`code`, `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.
+`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 Starter requirement. Its `requiredPlan` is
+`starter-v1`; select a Starter 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 surfaces, all available from the root for compatibility:
 
@@ -215,6 +271,8 @@ anchors, and resolved sprite dimensions. Its top-level `mapId` identifies the re
 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
@@ -236,8 +294,6 @@ Free cannot initiate Static Maps work. Starter consumes 15 shared API units for
 logical operation, including a distinct-key cache reuse. Downloading an immutable PNG, JPEG, or WebP
 consumes zero units.
 
-Docs: https://tileflow.dev/docs
-
 ## Team credentials
 
 A Team credential can serve multiple Maps. Pass `mapId` in the options to `createStaticMap` or

package/dist/{chunk-RGXE4HDY.js → chunk-4GPRPR33.js}

@@ -4,7 +4,7 @@ import {
   staticMapErrorResponseSchema,
   staticMapRequestErrorResponseSchema,
   validateStaticScene
-} from "./chunk-TBI5AED6.js";
+} from "./chunk-ALFVZ3PC.js";
 import {
   isSafeHttpUrl,
   jsonByteLength,

package/dist/{chunk-XMT7VJL5.js → chunk-4MXFTGQV.js}

@@ -3,7 +3,7 @@ import {
   normalizeStaticScene,
   staticAutoFitPlanSchema,
   validateStaticScene
-} from "./chunk-TBI5AED6.js";
+} from "./chunk-ALFVZ3PC.js";
 import {
   hashStableValue,
   isSafeHttpUrl,
@@ -130,12 +130,55 @@ var placementAnchorsSchema = z.object({
 }).strict().refine(anchorsHaveTerminalNulls, {
   message: "Placement anchors may become null only at the end of semantic order"
 });
+var iconCoordinate = z.number().int().nonnegative().max(2048);
+var iconStretchRegions = z.array(z.tuple([iconCoordinate, iconCoordinate])).min(1).max(2048);
+var iconLayoutSchema = z.object({
+  stretchX: iconStretchRegions.optional(),
+  stretchY: iconStretchRegions.optional(),
+  content: z.tuple([iconCoordinate, iconCoordinate, iconCoordinate, iconCoordinate]).optional()
+}).strict();
 var resolvedIconSchema = z.object({
+  layout: iconLayoutSchema.optional(),
+  // Verified asset defaults supplied by the manifest producer, never scene input.
+  appearance: z.object({
+    representation: z.literal("sdf"),
+    defaults: z.object({
+      color: z.string().min(1).max(128).refine(hasNoControlCharacters),
+      haloColor: z.string().min(1).max(128).refine(hasNoControlCharacters),
+      haloWidth: z.number().finite().min(0).max(2),
+      haloBlur: z.number().finite().min(0).max(1)
+    }).strict()
+  }).strict().optional(),
   height: z.number().int().positive().max(2048),
   icon: z.string().max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),
   overlayIndex: z.number().int().min(0).max(23),
   width: z.number().int().positive().max(2048)
-}).strict();
+}).strict().superRefine((icon, context) => {
+  const layout = icon.layout;
+  if (!layout) return;
+  let valid = Object.values(layout).some((value) => value !== void 0);
+  const content = layout.content;
+  if (content)
+    valid &&= content[0] < content[2] && content[1] < content[3] && content[2] <= icon.width && content[3] <= icon.height;
+  for (const [axis, bound, low, high] of [
+    ["stretchX", icon.width, content?.[0], content?.[2]],
+    ["stretchY", icon.height, content?.[1], content?.[3]]
+  ]) {
+    let end = 0;
+    for (const [from, to] of layout[axis] ?? []) {
+      valid &&= from >= end && from < to && to <= bound;
+      end = to;
+    }
+    if (layout[axis] && low !== void 0 && high !== void 0)
+      valid &&= layout[axis].some(([from, to]) => from < high && to > low);
+  }
+  if (!valid)
+    context.addIssue({
+      code: "custom",
+      path: ["layout"],
+      message: "Invalid icon layout for the resolved sprite dimensions"
+    });
+});
 var staticRenderCompositionSchema = z.object({
   anchors: placementAnchorsSchema,
   icons: z.array(resolvedIconSchema).max(24),

package/dist/{chunk-TBI5AED6.js → chunk-ALFVZ3PC.js}

@@ -23,12 +23,14 @@ var staticMapErrorResponseSchema = z.object({
   error: safeErrorTextSchema,
   remainingUnits: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
   requestId: safeErrorIdentifierSchema.optional(),
+  requiredPlan: safeErrorIdentifierSchema.optional(),
   retryable: z.boolean().optional()
 }).strip();
 var StaticMapError = class extends Error {
   code;
   remainingUnits;
   requestId;
+  requiredPlan;
   response;
   retryable;
   status;
@@ -39,6 +41,7 @@ var StaticMapError = class extends Error {
     this.code = parsed.code ?? null;
     this.remainingUnits = parsed.remainingUnits ?? null;
     this.requestId = parsed.requestId ?? null;
+    this.requiredPlan = parsed.requiredPlan ?? null;
     this.response = Object.freeze(parsed);
     this.retryable = parsed.retryable ?? null;
     this.status = status;

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export { S as StaticMapError, a as StaticMapErrorResponse, s as staticMapErrorResponseSchema } from './errors-B9rwehK0.js';
+export { S as StaticMapError, a as StaticMapErrorResponse, s as staticMapErrorResponseSchema } from './errors-CSz1xaDx.js';
 import { a as StaticAttributionPosition, j as StaticSceneInput } from './scene-contract-Cr6BNLz0.js';
 
 declare function stableStringify(value: unknown): string;

package/dist/client.js

@@ -10,11 +10,11 @@ import {
   staticMapHostedResultSchema,
   staticMapProcessingResultSchema,
   validateStaticMapIdempotencyKey
-} from "./chunk-RGXE4HDY.js";
+} from "./chunk-4GPRPR33.js";
 import {
   StaticMapError,
   staticMapErrorResponseSchema
-} from "./chunk-TBI5AED6.js";
+} from "./chunk-ALFVZ3PC.js";
 import {
   stableStringify
 } from "./chunk-6DWVCK64.js";

package/dist/{errors-B9rwehK0.d.ts → errors-CSz1xaDx.d.ts}

@@ -5,6 +5,7 @@ declare const staticMapErrorResponseSchema: z.ZodObject<{
     error: z.ZodString;
     remainingUnits: z.ZodOptional<z.ZodNumber>;
     requestId: z.ZodOptional<z.ZodString>;
+    requiredPlan: z.ZodOptional<z.ZodString>;
     retryable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 type StaticMapErrorResponse = z.infer<typeof staticMapErrorResponseSchema>;
@@ -12,6 +13,7 @@ declare class StaticMapError extends Error {
     readonly code: string | null;
     readonly remainingUnits: number | null;
     readonly requestId: string | null;
+    readonly requiredPlan: string | null;
     readonly response: StaticMapErrorResponse;
     readonly retryable: boolean | null;
     readonly status: number;

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { circle, compileStaticOverlays, line, marker, polygon, symbol } from './
 export { StaticAttributionEntry, StaticAttributionPlan, StaticAttributionProvenance, StaticAttributionSegment, StaticRenderComposition, StaticRenderManifest, StaticResolvedAttributionPosition, createRenderManifest, hashRenderManifest, hashStaticSceneRequest, staticAttributionEntrySchema, staticAttributionLimits, staticAttributionPlanSchema, staticAttributionPlanSchemaVersion, staticAttributionProvenanceSchema, staticAttributionSegmentSchema, staticRenderCompositionSchema, staticRenderCompositionSchemaVersion, staticRenderManifestSchema, staticRendererSchemaVersion, validateStaticRenderManifest } from './manifest.js';
 export { PreparedStaticMapRequest, STATIC_MAP_RESULT_MEDIA_TYPE, StaticMapAttributionEntry, StaticMapAttributionResult, StaticMapCreateOptions, StaticMapEndpointRequestOptions, StaticMapHostedResult, StaticMapImageResult, StaticMapResult, createStaticMap, createStaticMapIdempotencyKey, precacheStaticMap, prepareStaticMapRequest, requestStaticMapUntilReady, stableStringify, staticMapAttributionEntrySchema, staticMapAttributionResultSchema, staticMapHostedResultSchema, staticMapProcessingResultSchema, validateStaticMapIdempotencyKey } from './client.js';
 export { M as MAX_OVERLAY_LATITUDE, S as StaticAttributionMode, a as StaticAttributionPosition, b as StaticAttributionRequest, c as StaticCoordinate, d as StaticMapFormat, e as StaticOverlay, f as StaticOverlayInput, g as StaticOverlayPlacement, h as StaticPadding, i as StaticScene, j as StaticSceneInput, k as StaticSymbolAnchor, l as StaticSymbolCollision, m as StaticSymbolLabelAppearance, n as StaticSymbolLabelPosition, o as StaticSymbolLanguage, p as isSupportedStaticSymbolCodePoint, s as staticAttributionPositionSchema, q as staticAttributionRequestSchema, r as staticOverlayPlacements, t as staticOverlaySchema, u as staticSceneLimits, v as staticSceneSchema, w as staticSceneSchemaVersion, x as staticSymbolAnchors, y as staticSymbolCollisions, z as staticSymbolLabelAppearances, A as staticSymbolLabelPositions, B as staticSymbolLanguages } from './scene-contract-Cr6BNLz0.js';
-export { S as StaticMapError, a as StaticMapErrorResponse, s as staticMapErrorResponseSchema } from './errors-B9rwehK0.js';
+export { S as StaticMapError, a as StaticMapErrorResponse, s as staticMapErrorResponseSchema } from './errors-CSz1xaDx.js';
 import 'zod';

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   staticMapHostedResultSchema,
   staticMapProcessingResultSchema,
   validateStaticMapIdempotencyKey
-} from "./chunk-RGXE4HDY.js";
+} from "./chunk-4GPRPR33.js";
 import {
   createRenderManifest,
   hashRenderManifest,
@@ -26,7 +26,7 @@ import {
   staticRenderManifestSchema,
   staticRendererSchemaVersion,
   validateStaticRenderManifest
-} from "./chunk-XMT7VJL5.js";
+} from "./chunk-4MXFTGQV.js";
 import {
   circle,
   compileStaticOverlays,
@@ -42,7 +42,7 @@ import {
   staticMapErrorResponseSchema,
   staticMapRequestErrorResponseSchema,
   validateStaticScene
-} from "./chunk-TBI5AED6.js";
+} from "./chunk-ALFVZ3PC.js";
 import {
   MAX_OVERLAY_LATITUDE,
   isSupportedStaticSymbolCodePoint,

package/dist/manifest.d.ts

@@ -144,6 +144,20 @@ declare const staticRenderCompositionSchema: z.ZodObject<{
         'above-labels': z.ZodNull;
     }, z.core.$strict>;
     icons: z.ZodArray<z.ZodObject<{
+        layout: z.ZodOptional<z.ZodObject<{
+            stretchX: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+            stretchY: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+            content: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        }, z.core.$strict>>;
+        appearance: z.ZodOptional<z.ZodObject<{
+            representation: z.ZodLiteral<"sdf">;
+            defaults: z.ZodObject<{
+                color: z.ZodString;
+                haloColor: z.ZodString;
+                haloWidth: z.ZodNumber;
+                haloBlur: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
         height: z.ZodNumber;
         icon: z.ZodString;
         overlayIndex: z.ZodNumber;
@@ -227,6 +241,20 @@ declare const staticRenderManifestSchema: z.ZodObject<{
             'above-labels': z.ZodNull;
         }, z.core.$strict>;
         icons: z.ZodArray<z.ZodObject<{
+            layout: z.ZodOptional<z.ZodObject<{
+                stretchX: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+                stretchY: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+                content: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+            }, z.core.$strict>>;
+            appearance: z.ZodOptional<z.ZodObject<{
+                representation: z.ZodLiteral<"sdf">;
+                defaults: z.ZodObject<{
+                    color: z.ZodString;
+                    haloColor: z.ZodString;
+                    haloWidth: z.ZodNumber;
+                    haloBlur: z.ZodNumber;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
             height: z.ZodNumber;
             icon: z.ZodString;
             overlayIndex: z.ZodNumber;

package/dist/manifest.js

@@ -13,8 +13,8 @@ import {
   staticRenderManifestSchema,
   staticRendererSchemaVersion,
   validateStaticRenderManifest
-} from "./chunk-XMT7VJL5.js";
-import "./chunk-TBI5AED6.js";
+} from "./chunk-4MXFTGQV.js";
+import "./chunk-ALFVZ3PC.js";
 import "./chunk-6DWVCK64.js";
 export {
   createRenderManifest,

package/dist/scene.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { S as StaticMapError } from './errors-B9rwehK0.js';
+import { S as StaticMapError } from './errors-CSz1xaDx.js';
 import { j as StaticSceneInput, i as StaticScene } from './scene-contract-Cr6BNLz0.js';
 export { M as MAX_OVERLAY_LATITUDE, S as StaticAttributionMode, a as StaticAttributionPosition, b as StaticAttributionRequest, c as StaticCoordinate, d as StaticMapFormat, g as StaticOverlayPlacement, h as StaticPadding, k as StaticSymbolAnchor, l as StaticSymbolCollision, m as StaticSymbolLabelAppearance, n as StaticSymbolLabelPosition, o as StaticSymbolLanguage, p as isSupportedStaticSymbolCodePoint, s as staticAttributionPositionSchema, q as staticAttributionRequestSchema, r as staticOverlayPlacements, u as staticSceneLimits, v as staticSceneSchema, w as staticSceneSchemaVersion, x as staticSymbolAnchors, y as staticSymbolCollisions, z as staticSymbolLabelAppearances, A as staticSymbolLabelPositions, B as staticSymbolLanguages } from './scene-contract-Cr6BNLz0.js';
 

package/dist/scene.js

@@ -3,7 +3,7 @@ import {
   normalizeStaticScene,
   staticMapRequestErrorResponseSchema,
   validateStaticScene
-} from "./chunk-TBI5AED6.js";
+} from "./chunk-ALFVZ3PC.js";
 import {
   MAX_OVERLAY_LATITUDE,
   isSupportedStaticSymbolCodePoint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/static",
-  "version": "0.1.0-alpha.25",
+  "version": "0.1.0-alpha.27",
   "license": "Apache-2.0",
   "description": "Static map request schemas and helpers for Tileflow.",
   "type": "module",