@tileflow/dev 0.1.0-alpha.24 → 0.1.0-alpha.26

package/README.md

@@ -103,6 +103,9 @@ export async function createMapHandler() {
 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
@@ -120,15 +123,28 @@ Invalid compiled styles throw `TileflowStyleValidationError` with bounded issues
 structured; do not return executable config, local paths, credentials, or complete generated byte
 arrays from a public endpoint.
 
-## Locked Icon Set composition foundations
+## 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`, replacement ordinals, and local watch paths.
+`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`. Nothing selects a cache, an origin, or a transport from
+implicit process state, and 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
@@ -149,21 +165,26 @@ retirement support concurrent writers and corruption repair. Symlink entries are
 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.
 
-The existing 256-effective-icon, 2048-atlas-dimension, 4 MiB/file, and 8 MiB/package bounds still
-apply. 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. Normal CLI/build/framework and Hosted command integration follows separately; those
-existing entry points currently reject shared descriptors rather than silently dropping them.
+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. 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.
@@ -171,3 +192,9 @@ These references are also included under `docs/` in the installed package:
 - [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

@@ -5,6 +5,29 @@ and fonts are owned and published by `@tileflow/maps`; `@tileflow/dev` does not
 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

package/dist/artifacts.d.ts

@@ -1,7 +1,8 @@
-import { TileflowStyleOptions, MapLibreStyle } from '@tileflow/core';
-import { TileflowBuildCatalog, TileflowBuildStyles, TileflowMapBuildManifestV1, TileflowStyleInspection, TileflowMapBuildProvenanceV1, TileflowPreparedMapAssets } from '@tileflow/core/build';
+import { MapLibreStyle, TileflowViewConfig, TileflowStyleOptions } from '@tileflow/core';
+import { TileflowBuildCatalog, TileflowBuildStyles, TileflowMapBuildManifestV1, TileflowRendererDeploymentArtifact, TileflowStyleInspection, TileflowMapBuildProvenanceV1, TileflowPreparedMapAssets } from '@tileflow/core/build';
 import { TileflowRuntimeManifest } from '@tileflow/core/manifest';
-import { e as TileflowBuildAsset, P as PreparedTileflowBuildCatalog, r as TileflowSourceCatalog, d as PreparedTileflowCatalog } from './icons-CkLVtaP-.js';
+import { TileflowRenderer, TileflowNativeBuildRecord } from '@tileflow/core/native-profile';
+import { TileflowBuildAsset, TileflowIconResolutionOptions, PreparedTileflowBuildCatalog, TileflowSourceCatalog, PreparedTileflowCatalog } from './icons.js';
 export { defaultTileflowConfigPath } from './config.js';
 
 type TileflowLocalTilesetFile = Readonly<{
@@ -28,6 +29,10 @@ type TileflowArtifactDiagnostic = {
     message: string;
     path: string;
     phase?: string;
+    renderer?: 'native';
+    profile?: 'native-v1';
+    severity?: 'error';
+    suggestion?: string;
 };
 type TileflowArtifactSessionState = {
     status: 'building';
@@ -67,6 +72,24 @@ type TileflowArtifactSession = {
 };
 declare function createTileflowArtifactDiagnostics(error: unknown, cwd: string): TileflowArtifactDiagnostic[];
 
+type Input = Readonly<{
+    mapId: string;
+    buildManifest: TileflowMapBuildManifestV1;
+    styles: Readonly<Record<string, MapLibreStyle>>;
+    teamSources: Readonly<Record<string, Readonly<{
+        tileset: string;
+        type: 'raster' | 'vector';
+    }>>>;
+    assets: readonly TileflowBuildAsset[];
+    view?: TileflowViewConfig;
+}>;
+/**
+ * Prepare both representations from the same already compiled, asset-bound web family.
+ * This has no network or publication port. Call it before any authenticated remote operation.
+ * Logical Hosted placeholders are validated syntactically without granting delivery authority.
+ */
+declare function prepareTileflowHostedNativeDeployment(input: Input): Promise<TileflowRendererDeploymentArtifact>;
+
 /** Normalize a development route base. This is a URL pathname, never a filesystem path. */
 declare function normalizeTileflowBasePath(value?: string): string;
 /**
@@ -98,6 +121,15 @@ type TileflowBuildArtifactsOptions = {
     assetBaseUrl?: string;
     config?: string;
     cwd?: string;
+    /**
+     * Explicit shared Icon Set resolution settings for this build.
+     *
+     * Builds never resolve a catalog head. These options only choose the verified cache root,
+     * offline behavior, trusted delivery origins and the transport used to hydrate exact pins.
+     */
+    icons?: TileflowIconResolutionOptions;
+    /** Artifact renderer. Omission is identical to web; native uses a separate output directory. */
+    renderer?: TileflowRenderer;
     /** Build a memory-only compiler sidecar for local authoring tools. */
     inspection?: boolean;
     styleBaseUrl?: string;
@@ -109,6 +141,8 @@ type TileflowBuildStyleInspections = Record<string, Record<string, TileflowStyle
 type TileflowBuildArtifacts = {
     assets: TileflowBuildAsset[];
     buildManifest: TileflowMapBuildManifestV1;
+    /** Present only for native artifact preparation; never part of the runtime manifest. */
+    nativeBuild?: TileflowNativeBuildRecord;
     /** Releases local immutable snapshot references owned by this artifact generation. */
     dispose?: () => Promise<void>;
     manifest: TileflowRuntimeManifest;
@@ -138,7 +172,7 @@ type TileflowArtifactPlan = TileflowBuildArtifacts & {
     schemaVersion: typeof tileflowArtifactPlanSchemaVersion;
     sourceProject: TileflowSourceCatalog;
 };
-type CreateTileflowArtifactPlanOptions = Pick<TileflowBuildArtifactsOptions, 'apiBaseUrl' | 'assetBaseUrl' | 'inspection' | 'styleBaseUrl' | 'target'> & {
+type CreateTileflowArtifactPlanOptions = Pick<TileflowBuildArtifactsOptions, 'apiBaseUrl' | 'assetBaseUrl' | 'inspection' | 'renderer' | 'styleBaseUrl' | 'target'> & {
     inputFiles?: readonly string[];
 };
 type WriteTileflowArtifactPlanOptions = {
@@ -188,4 +222,4 @@ declare function assertTileflowSelfHostedManifestTarget(manifestPath: string, op
     overwriteHostedManifest?: boolean;
 }): Promise<void>;
 
-export { type CreateTileflowArtifactPlanOptions, PreparedTileflowBuildCatalog, PreparedTileflowCatalog, type TileflowArtifactAcquisition, type TileflowArtifactDiagnostic, type TileflowArtifactFile, type TileflowArtifactInputGraph, type TileflowArtifactPlan, type TileflowArtifactSession, type TileflowArtifactSessionOptions, type TileflowArtifactSessionState, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, TileflowBuildAsset, type TileflowBuildStyleInspections, TileflowHostedManifestOverwriteError, type TileflowLocalTilesetFile, TileflowLocalTilesetProductionError, type TileflowManifestOptions, TileflowSourceCatalog, type WriteTileflowArtifactPlanOptions, type WriteTileflowBuildArtifactsOptions, assertNoLocalTilesetsForProduction, assertTileflowSelfHostedManifestTarget, createTileflowArtifactDiagnostics, createTileflowArtifactPlan, createTileflowArtifactSession, createTileflowBuildArtifacts, createTileflowBuildProvenance, createTileflowManifest, createTileflowStyle, createTileflowStyles, disposeTileflowBuildArtifacts, getTileflowArtifactFiles, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowWatchPaths, isTileflowArtifactInputPath, joinTileflowPublicUrl, normalizeTileflowBasePath, prepareTileflowLocalTilesets, refreshTileflowArtifactSession, resolveTileflowArtifactPublicUrls, tileflowArtifactInventoryFileName, tileflowArtifactPlanSchemaVersion, tileflowArtifactSessionSchemaVersion, writeTileflowArtifactPlan, writeTileflowBuildArtifacts };
+export { type CreateTileflowArtifactPlanOptions, PreparedTileflowBuildCatalog, PreparedTileflowCatalog, type TileflowArtifactAcquisition, type TileflowArtifactDiagnostic, type TileflowArtifactFile, type TileflowArtifactInputGraph, type TileflowArtifactPlan, type TileflowArtifactSession, type TileflowArtifactSessionOptions, type TileflowArtifactSessionState, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, TileflowBuildAsset, type TileflowBuildStyleInspections, TileflowHostedManifestOverwriteError, TileflowIconResolutionOptions, type TileflowLocalTilesetFile, TileflowLocalTilesetProductionError, type TileflowManifestOptions, TileflowSourceCatalog, type WriteTileflowArtifactPlanOptions, type WriteTileflowBuildArtifactsOptions, assertNoLocalTilesetsForProduction, assertTileflowSelfHostedManifestTarget, createTileflowArtifactDiagnostics, createTileflowArtifactPlan, createTileflowArtifactSession, createTileflowBuildArtifacts, createTileflowBuildProvenance, createTileflowManifest, createTileflowStyle, createTileflowStyles, disposeTileflowBuildArtifacts, getTileflowArtifactFiles, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowWatchPaths, isTileflowArtifactInputPath, joinTileflowPublicUrl, normalizeTileflowBasePath, prepareTileflowHostedNativeDeployment, prepareTileflowLocalTilesets, refreshTileflowArtifactSession, resolveTileflowArtifactPublicUrls, tileflowArtifactInventoryFileName, tileflowArtifactPlanSchemaVersion, tileflowArtifactSessionSchemaVersion, writeTileflowArtifactPlan, writeTileflowBuildArtifacts };

package/dist/artifacts.js

@@ -15,6 +15,7 @@ import {
   getTileflowArtifactFiles,
   getTileflowWatchPaths,
   isTileflowArtifactInputPath,
+  prepareTileflowHostedNativeDeployment,
   prepareTileflowLocalTilesets,
   refreshTileflowArtifactSession,
   tileflowArtifactInventoryFileName,
@@ -22,7 +23,7 @@ import {
   tileflowArtifactSessionSchemaVersion,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
-} from "./chunk-XXVI42UZ.js";
+} from "./chunk-QAMFAM3S.js";
 import "./chunk-ONYQNLNA.js";
 import {
   getTileflowAssetBasePath,
@@ -30,9 +31,9 @@ import {
   joinTileflowPublicUrl,
   normalizeTileflowBasePath,
   resolveTileflowArtifactPublicUrls
-} from "./chunk-RSBV4L2Y.js";
-import "./chunk-NUHSYLLS.js";
-import "./chunk-BL3FK4GO.js";
+} from "./chunk-UTRO4IBQ.js";
+import "./chunk-EJPVUSX4.js";
+import "./chunk-7C4F6GAX.js";
 import "./chunk-KDFTE4Q5.js";
 import {
   defaultTileflowConfigPath
@@ -60,6 +61,7 @@ export {
   isTileflowArtifactInputPath,
   joinTileflowPublicUrl,
   normalizeTileflowBasePath,
+  prepareTileflowHostedNativeDeployment,
   prepareTileflowLocalTilesets,
   refreshTileflowArtifactSession,
   resolveTileflowArtifactPublicUrls,

package/dist/{chunk-MKPSQSMX.js → chunk-73YPFDPC.js}

@@ -1,6 +1,6 @@
 import {
   createTileflowCommandSummary
-} from "./chunk-LNCTVFUD.js";
+} from "./chunk-XHJBCVBB.js";
 import {
   assertValidTileflowStyle,
   sanitizeDiagnosticSecrets

package/dist/{chunk-BL3FK4GO.js → chunk-7C4F6GAX.js}

@@ -52,7 +52,7 @@ async function resolveTileflowAssetDirectories(directories, options) {
   const result = [];
   const seen = /* @__PURE__ */ new Map();
   for (const [index, directory] of directories.entries()) {
-    const configPath = `${options.configPath}.${index}`;
+    const configPath = `${options.configPath}.${index + (options.ordinalOffset ?? 0)}`;
     let candidate;
     let containmentRoot;
     let packageOwned = false;