create-honua-app 0.1.7 → 0.1.9

package/README.md

@@ -1,10 +1,12 @@
 # create-honua-app
 
 Scaffold a [Honua JavaScript SDK](https://github.com/honua-io/honua-sdk-js) map application — Vite + TypeScript,
-pinned to the certified SDK release, running a map on the first `npm run dev`.
+running a map on the first `npm run dev`. These commands explicitly pin the SDK version documented here;
+omit `--sdk-version` to follow the promoted release channel or this scaffold's certified fallback.
 
+<!-- doc-run: run ready-url="http://localhost:5173/" -->
 ```bash
-npm create honua-app@0.1.6 my-map
+npm create honua-app@latest my-map -- --sdk-version 0.1.16 # x-release-please-version
 cd my-map
 npm install
 npm run dev
@@ -27,11 +29,17 @@ create-honua-app [directory] [options]
 With `npm create`, pass CLI options after `--`:
 
 ```bash
-npm create honua-app@0.1.6 my-react-map -- --template react-ts
+npm create honua-app@latest my-react-map -- --template react-ts --sdk-version 0.1.16 # x-release-please-version
 ```
 
 ## Which SDK version a scaffold pins
 
+The scaffold and SDK publish independently. `npm create honua-app@latest` selects the scaffold;
+`--sdk-version` selects the SDK installed in the generated application. The explicit
+SDK versions in this published README describe this scaffold release, even when a
+newer SDK has shipped. Keep the flag when reproducing these examples, or select
+another published SDK version deliberately.
+
 The scaffold resolves `@honua/sdk-js` when it runs, from the `release-2026.1` npm dist-tag. Only a Honua release
 promotion moves that tag, so a newly promoted SDK reaches fresh scaffolds without a new `create-honua-app`. The
 generated `package.json` still records one exact version, so the app stays reproducible.
@@ -42,7 +50,7 @@ version this release of `create-honua-app` ships with. The default path never pi
 yourself, pass `--sdk-version`:
 
 ```bash
-npm create honua-app@0.1.6 my-pinned-map -- --sdk-version 0.1.13
+npm create honua-app@latest my-pinned-map -- --sdk-version 0.1.16 # x-release-please-version
 ```
 
 ## Templates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-honua-app",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Scaffold a Honua JavaScript SDK map application: Vite + TypeScript + MapLibre starters that connect and mount a source without hand-assembling peers",
   "license": "Apache-2.0",
   "author": "Honua",

package/templates/react-ts/README.md

@@ -62,3 +62,7 @@ npm run build
 ```
 
 The fixture data is synthetic demonstration data from the Honua SDK sample fixtures (Apache-2.0).
+
+## Live basemap
+
+The default fixture lane stays offline. When `VITE_HONUA_ENDPOINT` selects a live endpoint, the map uses keyless OpenFreeMap Positron (or Dark for the system theme) and keeps source attribution visible. Set `VITE_HONUA_BASEMAP_STYLE` to a custom/self-hosted style URL. A basemap asset failure leaves operational data and controls available with an actionable status. Keep the expanded source credits in screenshots and exports.

package/templates/react-ts/package.json

@@ -16,7 +16,7 @@
     "@bufbuild/protobuf": "2.13.0",
     "@connectrpc/connect": "2.1.2",
     "@connectrpc/connect-web": "2.1.2",
-    "@honua/sdk-js": "0.1.13",
+    "@honua/sdk-js": "0.1.14",
     "maplibre-gl": "6.4.1",
     "react": "19.2.8",
     "react-dom": "19.2.8"

package/templates/react-ts/src/App.tsx

@@ -4,6 +4,7 @@ import { maplibreRenderer } from "@honua/sdk-js/runtime";
 import * as maplibregl from "maplibre-gl";
 import type { RefObject } from "react";
 import { useEffect, useRef, useState } from "react";
+import { mountSampleOnlineBasemap } from "./online-basemap.js";
 
 import { FIXTURE_LAYER_PATH } from "./fixture-endpoint.js";
 
@@ -54,11 +55,17 @@ function useExternalMap(): { containerRef: RefObject<HTMLDivElement | null>; map
       style: BASEMAP_STYLE,
       center: INITIAL_VIEW.center,
       zoom: INITIAL_VIEW.zoom,
-      attributionControl: false,
+      attributionControl: { compact: true },
     });
+    const disposeBasemap = configuredEndpoint
+      ? mountSampleOnlineBasemap(created, {
+          styleUrl: import.meta.env.VITE_HONUA_BASEMAP_STYLE?.trim() || undefined,
+        })
+      : () => {};
     setMap(created);
     return () => {
       setMap(null);
+      disposeBasemap();
       created.remove();
     };
   }, []);

package/templates/react-ts/src/online-basemap.ts

@@ -0,0 +1,84 @@
+import * as runtime from "@honua/sdk-js/runtime";
+
+type HonuaOnlineBasemapTheme = "positron" | "liberty" | "dark";
+interface OnlineBasemapBinding {
+  activate(options: { theme: HonuaOnlineBasemapTheme; styleUrl?: string }): Promise<boolean>;
+  dispose(): void;
+}
+type OnlineBasemapConstructor = new (
+  map: MapLibreMap,
+  options: { onError: (message: string) => void; onReady: () => void },
+) => OnlineBasemapBinding;
+import type { Map as MapLibreMap } from "maplibre-gl";
+
+/** Explicit live-lane enhancement. Local fixture lanes never call this helper. */
+export function mountSampleOnlineBasemap(
+  map: MapLibreMap,
+  options: {
+    readonly styleUrl?: string;
+    readonly lightTheme?: Exclude<HonuaOnlineBasemapTheme, "dark">;
+    readonly styleEnvironmentVariable?: string;
+  } = {},
+): () => void {
+  const notice = document.createElement("div");
+  notice.setAttribute("role", "status");
+  notice.dataset.basemapStatus = "loading";
+  notice.style.cssText =
+    "position:absolute;left:12px;right:12px;bottom:40px;z-index:5;padding:8px 12px;background:Canvas;color:CanvasText;border:1px solid currentColor;border-radius:6px;font:13px system-ui;pointer-events:none;display:none";
+  map.getContainer().append(notice);
+  // Older published SDKs can still run the local fixture lane. A live map
+  // explicitly reports the required upgrade instead of failing module loading.
+  const Binding = (runtime as unknown as { readonly HonuaOnlineBasemapBinding?: OnlineBasemapConstructor })
+    .HonuaOnlineBasemapBinding;
+  if (typeof Binding !== "function") {
+    notice.textContent =
+      "Online basemaps require a newer @honua/sdk-js release with HonuaOnlineBasemapBinding. Upgrade @honua/sdk-js after the basemap SDK release is published, then reload. Operational data remains usable.";
+    notice.dataset.basemapStatus = "error";
+    notice.style.display = "block";
+    return () => notice.remove();
+  }
+  const binding = new Binding(map, {
+    onError: (message) => {
+      notice.textContent = `${message} Set ${options.styleEnvironmentVariable ?? "VITE_HONUA_BASEMAP_STYLE"} to your custom/self-hosted style URL.`;
+      notice.dataset.basemapStatus = "error";
+      notice.style.display = "block";
+    },
+    onReady: () => {
+      notice.textContent = "";
+      notice.dataset.basemapStatus = "ready";
+      notice.style.display = "none";
+    },
+  });
+  const preferred = matchMedia("(prefers-color-scheme: dark)");
+  let pendingTheme: HonuaOnlineBasemapTheme | undefined;
+  const flush = () => {
+    if (!pendingTheme || !map.isStyleLoaded()) return;
+    const theme = pendingTheme;
+    pendingTheme = undefined;
+    void binding.activate({ theme, styleUrl: options.styleUrl });
+  };
+  const update = () => {
+    const selected = document.documentElement.dataset.theme;
+    const dark = selected === "dark" || (!selected && preferred.matches);
+    pendingTheme = dark ? "dark" : (options.lightTheme ?? "positron");
+    flush();
+  };
+  const observer = new MutationObserver(update);
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] });
+  preferred.addEventListener("change", update);
+  // Theme changes during tile/sprite loading must survive until the renderer
+  // is ready again. Consume only the latest pending theme, once per update.
+  map.on("idle", flush);
+  map.once("load", flush);
+  update();
+  const dispose = () => {
+    map.off("load", flush);
+    map.off("idle", flush);
+    observer.disconnect();
+    preferred.removeEventListener("change", update);
+    binding.dispose();
+    notice.remove();
+  };
+  // Dispose before remove(), while the renderer's style resources still exist.
+  return dispose;
+}

package/templates/vanilla-ts/README.md

@@ -59,3 +59,7 @@ npm run build
 ```
 
 The fixture data is synthetic demonstration data from the Honua SDK sample fixtures (Apache-2.0).
+
+## Live basemap
+
+The default fixture lane stays offline. When `VITE_HONUA_ENDPOINT` selects a live endpoint, the map uses keyless OpenFreeMap Positron (or Dark for the system theme) and keeps source attribution visible. Set `VITE_HONUA_BASEMAP_STYLE` to a custom/self-hosted style URL. A basemap asset failure leaves operational data and controls available with an actionable status. Keep the expanded source credits in screenshots and exports.

package/templates/vanilla-ts/package.json

@@ -16,7 +16,7 @@
     "@bufbuild/protobuf": "2.13.0",
     "@connectrpc/connect": "2.1.2",
     "@connectrpc/connect-web": "2.1.2",
-    "@honua/sdk-js": "0.1.13",
+    "@honua/sdk-js": "0.1.14",
     "maplibre-gl": "6.4.1"
   },
   "devDependencies": {

package/templates/vanilla-ts/src/main.ts

@@ -1,3 +1,4 @@
+import { mountSampleOnlineBasemap } from "./online-basemap.js";
 import "./maplibre-worker.js";
 import "maplibre-gl/dist/maplibre-gl.css";
 
@@ -16,7 +17,7 @@ const BASEMAP_STYLE = {
   layers: [{ id: "background", type: "background", paint: { "background-color": "#0e1a17" } }],
 };
 
-const MAP_OPTIONS = { center: [-157.873, 21.2985], zoom: 11.4, attributionControl: false };
+const MAP_OPTIONS = { center: [-157.873, 21.2985], zoom: 11.4, attributionControl: { compact: true } };
 
 /** Bounded row budget. Honua never mounts a truncated result silently. */
 const MAX_FEATURES = 250;
@@ -99,6 +100,21 @@ async function run(): Promise<void> {
       rendererOptions: { mapOptions: MAP_OPTIONS },
     });
     await mounted.ready;
+    const rawMap = mounted.raw("maplibre");
+    const disposeBasemap =
+      configuredEndpoint && rawMap
+        ? mountSampleOnlineBasemap(rawMap as maplibregl.Map, {
+            styleUrl: import.meta.env.VITE_HONUA_BASEMAP_STYLE?.trim() || undefined,
+          })
+        : () => {};
+    window.addEventListener(
+      "pagehide",
+      () => {
+        disposeBasemap();
+        void honua.dispose();
+      },
+      { once: true },
+    );
     stage("mount", "done", "mounted");
     element("status").textContent = "The accepted plan is mounted. Every stage above ran through the public SDK API.";
   } catch (error) {

package/templates/vanilla-ts/src/online-basemap.ts

@@ -0,0 +1,84 @@
+import * as runtime from "@honua/sdk-js/runtime";
+
+type HonuaOnlineBasemapTheme = "positron" | "liberty" | "dark";
+interface OnlineBasemapBinding {
+  activate(options: { theme: HonuaOnlineBasemapTheme; styleUrl?: string }): Promise<boolean>;
+  dispose(): void;
+}
+type OnlineBasemapConstructor = new (
+  map: MapLibreMap,
+  options: { onError: (message: string) => void; onReady: () => void },
+) => OnlineBasemapBinding;
+import type { Map as MapLibreMap } from "maplibre-gl";
+
+/** Explicit live-lane enhancement. Local fixture lanes never call this helper. */
+export function mountSampleOnlineBasemap(
+  map: MapLibreMap,
+  options: {
+    readonly styleUrl?: string;
+    readonly lightTheme?: Exclude<HonuaOnlineBasemapTheme, "dark">;
+    readonly styleEnvironmentVariable?: string;
+  } = {},
+): () => void {
+  const notice = document.createElement("div");
+  notice.setAttribute("role", "status");
+  notice.dataset.basemapStatus = "loading";
+  notice.style.cssText =
+    "position:absolute;left:12px;right:12px;bottom:40px;z-index:5;padding:8px 12px;background:Canvas;color:CanvasText;border:1px solid currentColor;border-radius:6px;font:13px system-ui;pointer-events:none;display:none";
+  map.getContainer().append(notice);
+  // Older published SDKs can still run the local fixture lane. A live map
+  // explicitly reports the required upgrade instead of failing module loading.
+  const Binding = (runtime as unknown as { readonly HonuaOnlineBasemapBinding?: OnlineBasemapConstructor })
+    .HonuaOnlineBasemapBinding;
+  if (typeof Binding !== "function") {
+    notice.textContent =
+      "Online basemaps require a newer @honua/sdk-js release with HonuaOnlineBasemapBinding. Upgrade @honua/sdk-js after the basemap SDK release is published, then reload. Operational data remains usable.";
+    notice.dataset.basemapStatus = "error";
+    notice.style.display = "block";
+    return () => notice.remove();
+  }
+  const binding = new Binding(map, {
+    onError: (message) => {
+      notice.textContent = `${message} Set ${options.styleEnvironmentVariable ?? "VITE_HONUA_BASEMAP_STYLE"} to your custom/self-hosted style URL.`;
+      notice.dataset.basemapStatus = "error";
+      notice.style.display = "block";
+    },
+    onReady: () => {
+      notice.textContent = "";
+      notice.dataset.basemapStatus = "ready";
+      notice.style.display = "none";
+    },
+  });
+  const preferred = matchMedia("(prefers-color-scheme: dark)");
+  let pendingTheme: HonuaOnlineBasemapTheme | undefined;
+  const flush = () => {
+    if (!pendingTheme || !map.isStyleLoaded()) return;
+    const theme = pendingTheme;
+    pendingTheme = undefined;
+    void binding.activate({ theme, styleUrl: options.styleUrl });
+  };
+  const update = () => {
+    const selected = document.documentElement.dataset.theme;
+    const dark = selected === "dark" || (!selected && preferred.matches);
+    pendingTheme = dark ? "dark" : (options.lightTheme ?? "positron");
+    flush();
+  };
+  const observer = new MutationObserver(update);
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] });
+  preferred.addEventListener("change", update);
+  // Theme changes during tile/sprite loading must survive until the renderer
+  // is ready again. Consume only the latest pending theme, once per update.
+  map.on("idle", flush);
+  map.once("load", flush);
+  update();
+  const dispose = () => {
+    map.off("load", flush);
+    map.off("idle", flush);
+    observer.disconnect();
+    preferred.removeEventListener("change", update);
+    binding.dispose();
+    notice.remove();
+  };
+  // Dispose before remove(), while the renderer's style resources still exist.
+  return dispose;
+}

package/templates.manifest.json

@@ -4,7 +4,7 @@
   "sdk": {
     "package": "@honua/sdk-js",
     "channel": "release-2026.1",
-    "version": "0.1.13"
+    "version": "0.1.14"
   },
   "repository": {
     "owner": "honua-io",