create-honua-app 0.1.1 → 0.1.4

package/README.md

@@ -33,7 +33,7 @@ npm create honua-app@latest my-map -- --template react-ts
 | Template | What it shows |
 | --- | --- |
 | `vanilla-ts` | `connect → inspect → explain → query → mount`: the SDK owns the MapLibre map and mounts an accepted query plan. |
-| `react-ts` | The app owns a plain `maplibre-gl` map; `useMountedSource` from `@honua/sdk-js/react` mounts the discovered source onto it. |
+| `react-ts` | The app owns a plain `maplibre-gl` map; the same kernel connection inspects, explains, queries, and mounts onto it. |
 
 Both starters ship a committed GeoServices fixture served by the Vite dev and preview servers, so the green path
 never depends on a third-party endpoint, an account, or an API key. Set `VITE_HONUA_ENDPOINT` to run the same code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-honua-app",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "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",
@@ -17,7 +17,16 @@
     "access": "public",
     "provenance": true
   },
-  "keywords": ["gis", "geospatial", "maplibre", "typescript", "honua", "scaffold", "starter", "create-app"],
+  "keywords": [
+    "gis",
+    "geospatial",
+    "maplibre",
+    "typescript",
+    "honua",
+    "scaffold",
+    "starter",
+    "create-app"
+  ],
   "type": "module",
   "bin": {
     "create-honua-app": "bin/create-honua-app.mjs"
@@ -25,7 +34,14 @@
   "exports": {
     "./package.json": "./package.json"
   },
-  "files": ["bin", "lib", "templates", "templates.manifest.json", "README.md", "LICENSE"],
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "templates.manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=20.19.0"
   }

package/templates/react-ts/README.md

@@ -1,10 +1,10 @@
 # Honua map app (React + TypeScript)
 
 A Vite + React + TypeScript starter for the [Honua JavaScript SDK](https://github.com/honua-io/honua-sdk-js). The app
-owns a plain `maplibre-gl` map and the SDK's React bridge mounts a discovered source onto it:
+owns a plain `maplibre-gl` map and runs the kernel lifecycle against it:
 
 ```text
-connect → source → useMountedSource
+connect → inspect → explain → mount
 ```
 
 ## Run it
@@ -34,14 +34,14 @@ endpoint or a server-side proxy.
 
 | File | Why |
 | --- | --- |
-| `src/App.tsx` | Connection, query, and the mounted-source hook. Change the query here. |
-| `src/main.tsx` | React root. `StrictMode` stays on: the SDK hooks are StrictMode-safe. |
+| `src/App.tsx` | Connection, accepted query plan, and kernel-owned mount lifecycle. Change the query here. |
+| `src/main.tsx` | React root. `StrictMode` stays on: cancellation and disposal make remounts safe. |
 | `src/fixture-endpoint.ts` | The same-origin path the offline fixture is served on. |
+| `src/maplibre-worker.ts` | MapLibre 6's ESM worker URL, resolved through Vite. Leave it alone unless you swap the renderer. |
 | `vite.config.ts` | The fixture service. Delete it once you point the app at a real endpoint. |
 
-`HonuaMapProvider` publishes an app-owned map to descendants when the map is created deeper in the tree; this starter
-passes the map to `useMountedSource` directly. Add `@vitejs/plugin-react` if you want React Fast Refresh — Vite
-compiles the JSX without it.
+The starter passes its app-owned map directly to `connection.mount` and disposes the kernel when React tears the
+effect down. Add `@vitejs/plugin-react` if you want React Fast Refresh — Vite compiles the JSX without it.
 
 ## Dependencies
 
@@ -49,10 +49,10 @@ compiles the JSX without it.
 `@connectrpc` packages are the SDK's optional transport peers: they are installed and pinned here so the bundle builds
 without any peer-dependency assembly, and they are what a Honua-server connection uses.
 
-This starter pins **MapLibre GL JS 5.24.0**, the major the published `@honua/sdk-js` release accepts as an optional
-peer. MapLibre 6 is supported by the SDK source (`^5.0.0 || ^6.0.0`) and ships in the next release; upgrading to 6.x
-also means configuring MapLibre's ESM worker before the first map is created — under Vite, `setWorkerUrl` with
-`import maplibreWorkerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url"`.
+This starter pins **MapLibre GL JS 6.1.0**, which the published `@honua/sdk-js` release accepts as an optional peer
+(`^5.0.0 || ^6.0.0`). MapLibre 6 is ESM-only and loads its worker as a separate module, so `src/maplibre-worker.ts`
+calls `setWorkerUrl` with Vite's `?worker&url` import before the first map is created; `src/main.tsx` imports it
+first. Downgrading to MapLibre 5 is supported by the SDK and means deleting that module and its import.
 
 ## Checks
 

package/templates/react-ts/package.json

@@ -16,8 +16,8 @@
     "@bufbuild/protobuf": "2.13.0",
     "@connectrpc/connect": "2.1.2",
     "@connectrpc/connect-web": "2.1.2",
-    "@honua/sdk-js": "0.1.2-beta.0",
-    "maplibre-gl": "5.24.0",
+    "@honua/sdk-js": "0.1.10-beta.0",
+    "maplibre-gl": "6.1.0",
     "react": "19.2.8",
     "react-dom": "19.2.8"
   },

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

@@ -1,6 +1,6 @@
 import { createHonua } from "@honua/sdk-js";
-import type { ConnectProtocolHint, Source } from "@honua/sdk-js";
-import { useMountedSource } from "@honua/sdk-js/react";
+import type { ConnectProtocolHint, RendererDiagnostic } from "@honua/sdk-js";
+import { maplibreRenderer } from "@honua/sdk-js/runtime";
 import * as maplibregl from "maplibre-gl";
 import type { RefObject } from "react";
 import { useEffect, useRef, useState } from "react";
@@ -34,9 +34,10 @@ const PROTOCOL = (
 const DATA_LANE = configuredEndpoint && configuredEndpoint.length > 0 ? "Live endpoint" : "Committed fixture";
 
 interface ConnectionState {
-  readonly source: Source | null;
   readonly sourceId?: string;
   readonly protocol?: string;
+  readonly diagnostics?: readonly RendererDiagnostic[];
+  readonly mounted: boolean;
   readonly error?: string;
 }
 
@@ -65,54 +66,67 @@ function useExternalMap(): { containerRef: RefObject<HTMLDivElement | null>; map
   return { containerRef, map };
 }
 
-/** Connect once per effect run and publish the discovered source. */
-function useHonuaSource(): ConnectionState {
-  const [state, setState] = useState<ConnectionState>({ source: null });
+/** Run the canonical kernel-owned lifecycle against the app-owned map. */
+function useHonuaMap(map: maplibregl.Map | null): ConnectionState {
+  const [state, setState] = useState<ConnectionState>({ mounted: false });
 
   useEffect(() => {
+    if (!map) return;
     const honua = createHonua();
-    let cancelled = false;
+    const cancellation = new AbortController();
     void (async () => {
       try {
         const connection = await honua.connect(
           { url: ENDPOINT, protocol: PROTOCOL },
-          { authorizationScopeFingerprint: "anonymous-public" },
+          { authorizationScopeFingerprint: "anonymous-public", signal: cancellation.signal },
         );
-        const inspection = await connection.inspect();
+        const inspection = await connection.inspect({ signal: cancellation.signal });
         const sourceId = inspection.defaultSourceId ?? inspection.sources[0]?.descriptor.id;
         if (!sourceId) throw new Error("The endpoint advertised no queryable source.");
-        if (cancelled) return;
-        setState({ source: connection.source(sourceId), sourceId, protocol: inspection.protocol });
+        const plan = await connection.explain(QUERY, { sourceId, signal: cancellation.signal });
+        const mounted = await connection.mount(map, {
+          renderer: maplibreRenderer(maplibregl),
+          query: plan,
+          sourceId,
+          signal: cancellation.signal,
+        });
+        await mounted.ready;
+        setState({
+          sourceId,
+          protocol: inspection.protocol,
+          diagnostics: mounted.diagnostics,
+          mounted: true,
+        });
       } catch (error) {
-        if (!cancelled) setState({ source: null, error: error instanceof Error ? error.message : String(error) });
+        if (!cancellation.signal.aborted) {
+          setState({ mounted: false, error: error instanceof Error ? error.message : String(error) });
+        }
       }
     })();
     return () => {
-      cancelled = true;
+      cancellation.abort();
       void honua.dispose();
     };
-  }, []);
+  }, [map]);
 
   return state;
 }
 
 export function App() {
   const { containerRef, map } = useExternalMap();
-  const connection = useHonuaSource();
-  const mounted = useMountedSource(map, connection.source, { query: QUERY, fitBounds: true });
-
-  const failure = connection.error ?? (mounted.error instanceof Error ? mounted.error.message : undefined);
-  const status = failure
-    ? `The workflow stopped: ${failure}`
-    : mounted.handle
-      ? "The queried source is mounted through the React bridge."
+  const connection = useHonuaMap(map);
+
+  const status = connection.error
+    ? `The workflow stopped: ${connection.error}`
+    : connection.mounted
+      ? "The accepted plan is mounted through the kernel lifecycle."
       : "Connecting, discovering, and mounting…";
 
   return (
     <main className="app">
       <section className="panel" aria-label="Workflow">
         <p className="eyebrow">Honua JavaScript SDK · React</p>
-        <h1 className="title">connect → source → useMountedSource</h1>
+        <h1 className="title">connect → inspect → explain → query → mount</h1>
         <output className="status" aria-live="polite">
           {status}
         </output>
@@ -135,11 +149,7 @@ export function App() {
           </div>
           <div>
             <dt>Strategy</dt>
-            <dd>{mounted.diagnostics?.strategy ?? "—"}</dd>
-          </div>
-          <div>
-            <dt>Features</dt>
-            <dd id="fact-features">{mounted.diagnostics?.featureCount ?? "—"}</dd>
+            <dd>{connection.diagnostics?.find((item) => item.strategy)?.strategy ?? "—"}</dd>
           </div>
         </dl>
         <p className="hint">

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

@@ -1,3 +1,4 @@
+import "./maplibre-worker.js";
 import "maplibre-gl/dist/maplibre-gl.css";
 
 import { StrictMode } from "react";
@@ -9,8 +10,8 @@ import "./styles.css";
 const container = document.getElementById("root");
 if (!container) throw new Error("Missing #root element");
 
-// StrictMode double-invokes effects in development. The SDK's React hooks are
-// StrictMode-safe, so the mount/unmount/mount cycle never leaks a map source.
+// StrictMode double-invokes effects in development. App owns cancellation and
+// SDK disposal, so the mount/unmount/mount cycle never leaks a map source.
 createRoot(container).render(
   <StrictMode>
     <App />

package/templates/react-ts/src/maplibre-worker.ts

@@ -0,0 +1,14 @@
+// MapLibre GL JS 6 is ESM-only and loads its worker as a separate module,
+// resolving `./maplibre-gl-worker.mjs` against its own `import.meta.url`. That
+// URL survives a dev server but not a production bundle, where MapLibre's own
+// module has been rewritten into an app chunk that sits nowhere near the
+// installed package and its sibling worker file. Vite's
+// `?worker&url` pipeline emits the worker as a real asset and hands back the
+// hashed URL it was emitted to, which is what `setWorkerUrl` needs.
+//
+// Import this module before the first map is created; `src/main.tsx` does.
+
+import { setWorkerUrl } from "maplibre-gl";
+import maplibreWorkerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url";
+
+setWorkerUrl(maplibreWorkerUrl);

package/templates/vanilla-ts/README.md

@@ -36,6 +36,7 @@ endpoint or a server-side proxy.
 | --- | --- |
 | `src/main.ts` | The whole workflow: connect, inspect, explain, query, mount. Change the query here. |
 | `src/fixture-endpoint.ts` | The same-origin path the offline fixture is served on. |
+| `src/maplibre-worker.ts` | MapLibre 6's ESM worker URL, resolved through Vite. Leave it alone unless you swap the renderer. |
 | `vite.config.ts` | The fixture service. Delete it once you point the app at a real endpoint. |
 | `fixtures/` | The committed GeoServices layer description and its query response. |
 
@@ -45,10 +46,10 @@ endpoint or a server-side proxy.
 `@connectrpc` packages are the SDK's optional transport peers: they are installed and pinned here so the bundle builds
 without any peer-dependency assembly, and they are what a Honua-server connection uses.
 
-This starter pins **MapLibre GL JS 5.24.0**, the major the published `@honua/sdk-js` release accepts as an optional
-peer. MapLibre 6 is supported by the SDK source (`^5.0.0 || ^6.0.0`) and ships in the next release; upgrading to 6.x
-also means configuring MapLibre's ESM worker before the first map is created — under Vite, `setWorkerUrl` with
-`import maplibreWorkerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url"`.
+This starter pins **MapLibre GL JS 6.1.0**, which the published `@honua/sdk-js` release accepts as an optional peer
+(`^5.0.0 || ^6.0.0`). MapLibre 6 is ESM-only and loads its worker as a separate module, so `src/maplibre-worker.ts`
+calls `setWorkerUrl` with Vite's `?worker&url` import before the first map is created; `src/main.ts` imports it first.
+Downgrading to MapLibre 5 is supported by the SDK and means deleting that module and its import.
 
 ## Checks
 

package/templates/vanilla-ts/package.json

@@ -16,8 +16,8 @@
     "@bufbuild/protobuf": "2.13.0",
     "@connectrpc/connect": "2.1.2",
     "@connectrpc/connect-web": "2.1.2",
-    "@honua/sdk-js": "0.1.2-beta.0",
-    "maplibre-gl": "5.24.0"
+    "@honua/sdk-js": "0.1.10-beta.0",
+    "maplibre-gl": "6.1.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

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

@@ -1,3 +1,4 @@
+import "./maplibre-worker.js";
 import "maplibre-gl/dist/maplibre-gl.css";
 
 import { createHonua } from "@honua/sdk-js";

package/templates/vanilla-ts/src/maplibre-worker.ts

@@ -0,0 +1,14 @@
+// MapLibre GL JS 6 is ESM-only and loads its worker as a separate module,
+// resolving `./maplibre-gl-worker.mjs` against its own `import.meta.url`. That
+// URL survives a dev server but not a production bundle, where MapLibre's own
+// module has been rewritten into an app chunk that sits nowhere near the
+// installed package and its sibling worker file. Vite's
+// `?worker&url` pipeline emits the worker as a real asset and hands back the
+// hashed URL it was emitted to, which is what `setWorkerUrl` needs.
+//
+// Import this module before the first map is created; `src/main.ts` does.
+
+import { setWorkerUrl } from "maplibre-gl";
+import maplibreWorkerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url";
+
+setWorkerUrl(maplibreWorkerUrl);

package/templates.manifest.json

@@ -3,7 +3,7 @@
   "schemaVersion": 1,
   "sdk": {
     "package": "@honua/sdk-js",
-    "version": "0.1.2-beta.0"
+    "version": "0.1.10-beta.0"
   },
   "repository": {
     "owner": "honua-io",
@@ -42,7 +42,7 @@
     {
       "id": "react-ts",
       "title": "React TypeScript",
-      "summary": "Vite + React + TypeScript app that mounts the same accepted plan through @honua/sdk-js/react hooks on an app-owned MapLibre map.",
+      "summary": "Vite + React + TypeScript app that mounts one accepted plan through the SDK kernel on an app-owned MapLibre map.",
       "path": "packages/create-honua-app/templates/react-ts",
       "entryFile": "src/App.tsx",
       "dataLane": "fixture",