create-honua-app 0.1.1

package/templates/vanilla-ts/README.md

@@ -0,0 +1,60 @@
+# Honua map app (vanilla TypeScript)
+
+A Vite + TypeScript starter for the [Honua JavaScript SDK](https://github.com/honua-io/honua-sdk-js). It runs the
+SDK's protocol-neutral workflow end to end:
+
+```text
+connect → inspect → explain → query → mount
+```
+
+## Run it
+
+```bash
+npm install
+npm run dev
+```
+
+The default lane serves a committed GeoServices fixture from the Vite dev server, so the first map needs no account,
+no API key, and no third-party network call. The same fixture is served by `npm run preview` after `npm run build`.
+
+## Point it at live data
+
+```bash
+VITE_HONUA_ENDPOINT=https://your-public-service.example/rest/services/example/FeatureServer/0 npm run dev
+```
+
+- `VITE_HONUA_ENDPOINT` — an anonymous, CORS-enabled GeoServices FeatureServer layer or OGC API Features landing page.
+- `VITE_HONUA_PROTOCOL` — `auto`, `geoservices-feature-service`, or `ogc-features` (default:
+  `geoservices-feature-service`, which matches the fixture).
+
+Do not put durable credentials in Vite environment variables: Vite embeds them in public JavaScript. Use an anonymous
+endpoint or a server-side proxy.
+
+## What to edit
+
+| File | Why |
+| --- | --- |
+| `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. |
+| `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. |
+
+## Dependencies
+
+`@honua/sdk-js` and `maplibre-gl` are the two packages this app calls directly. `@bufbuild/protobuf` and the two
+`@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"`.
+
+## Checks
+
+```bash
+npm run typecheck
+npm run build
+```
+
+The fixture data is synthetic demonstration data from the Honua SDK sample fixtures (Apache-2.0).

package/templates/vanilla-ts/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.env.local
+*.log
+.DS_Store

package/templates/vanilla-ts/fixtures/features.json

@@ -0,0 +1,46 @@
+{
+  "objectIdFieldName": "OBJECTID",
+  "geometryType": "esriGeometryPolygon",
+  "spatialReference": { "wkid": 4326 },
+  "fields": [
+    { "name": "OBJECTID", "type": "esriFieldTypeOID", "alias": "OBJECTID" },
+    { "name": "NAME", "type": "esriFieldTypeString", "alias": "Name" },
+    { "name": "STATUS", "type": "esriFieldTypeString", "alias": "Status" },
+    { "name": "CATEGORY", "type": "esriFieldTypeString", "alias": "Category" }
+  ],
+  "features": [
+    {
+      "attributes": {
+        "OBJECTID": 1,
+        "NAME": "Civic center service zone",
+        "STATUS": "Monitoring",
+        "CATEGORY": "Operations"
+      },
+      "geometry": {
+        "rings": [[[-157.866, 21.311], [-157.856, 21.311], [-157.856, 21.302], [-157.866, 21.302], [-157.866, 21.311]]]
+      }
+    },
+    {
+      "attributes": {
+        "OBJECTID": 2,
+        "NAME": "Harbor response district",
+        "STATUS": "Field review",
+        "CATEGORY": "Maritime"
+      },
+      "geometry": {
+        "rings": [[[-157.891, 21.304], [-157.879, 21.304], [-157.879, 21.294], [-157.891, 21.294], [-157.891, 21.304]]]
+      }
+    },
+    {
+      "attributes": {
+        "OBJECTID": 3,
+        "NAME": "Kakaako utility corridor",
+        "STATUS": "Ready",
+        "CATEGORY": "Infrastructure"
+      },
+      "geometry": {
+        "rings": [[[-157.87, 21.296], [-157.856, 21.296], [-157.856, 21.286], [-157.87, 21.286], [-157.87, 21.296]]]
+      }
+    }
+  ]
+}

package/templates/vanilla-ts/fixtures/layer.json

@@ -0,0 +1,34 @@
+{
+  "currentVersion": 11.3,
+  "id": 0,
+  "name": "Honolulu operations areas",
+  "type": "Feature Layer",
+  "description": "The same three synthetic First Map polygons exposed by the OGC API Features projection.",
+  "copyrightText": "Copyright Honua contributors; synthetic demonstration data.",
+  "provenance": {
+    "source": "honua-sdk-js test/fixtures/honua-quickstart-demo",
+    "retrievedAt": "2026-07-13T00:00:00.000Z"
+  },
+  "geometryType": "esriGeometryPolygon",
+  "objectIdField": "OBJECTID",
+  "maxRecordCount": 25,
+  "advancedQueryCapabilities": {
+    "supportsPagination": true,
+    "supportsReturningQueryExtent": false,
+    "supportsStatistics": false
+  },
+  "extent": {
+    "xmin": -157.891,
+    "ymin": 21.286,
+    "xmax": -157.856,
+    "ymax": 21.311,
+    "spatialReference": { "wkid": 4326 }
+  },
+  "fields": [
+    { "name": "OBJECTID", "type": "esriFieldTypeOID", "alias": "OBJECTID" },
+    { "name": "NAME", "type": "esriFieldTypeString", "alias": "Name" },
+    { "name": "STATUS", "type": "esriFieldTypeString", "alias": "Status" },
+    { "name": "CATEGORY", "type": "esriFieldTypeString", "alias": "Category" }
+  ],
+  "capabilities": "Query"
+}

package/templates/vanilla-ts/index.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Honua map app</title>
+  </head>
+  <body>
+    <main class="app">
+      <section class="panel" aria-label="Workflow">
+        <p class="eyebrow">Honua JavaScript SDK</p>
+        <h1 class="title">connect → inspect → explain → query → mount</h1>
+        <p id="status" class="status" role="status" aria-live="polite">Starting the workflow…</p>
+        <ol class="stages">
+          <li data-stage="connect"><span class="stage-name">Connect</span><span class="stage-state">waiting</span></li>
+          <li data-stage="inspect"><span class="stage-name">Inspect</span><span class="stage-state">waiting</span></li>
+          <li data-stage="explain"><span class="stage-name">Explain</span><span class="stage-state">waiting</span></li>
+          <li data-stage="query"><span class="stage-name">Query</span><span class="stage-state">waiting</span></li>
+          <li data-stage="mount"><span class="stage-name">Mount</span><span class="stage-state">waiting</span></li>
+        </ol>
+        <dl class="facts">
+          <div><dt>Data lane</dt><dd id="fact-mode">—</dd></div>
+          <div><dt>Endpoint</dt><dd id="fact-endpoint">—</dd></div>
+          <div><dt>Protocol</dt><dd id="fact-protocol">—</dd></div>
+          <div><dt>Source</dt><dd id="fact-source">—</dd></div>
+          <div><dt>Features</dt><dd id="fact-features">—</dd></div>
+        </dl>
+        <p class="hint">
+          Edit <code>src/main.ts</code> to change the query, or set <code>VITE_HONUA_ENDPOINT</code> to run the same
+          workflow against a live public service.
+        </p>
+      </section>
+      <div id="map" class="map" role="application" aria-label="Mounted map"></div>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/vanilla-ts/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "honua-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@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"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vite": "8.2.0"
+  }
+}

package/templates/vanilla-ts/src/fixture-endpoint.ts

@@ -0,0 +1,9 @@
+/**
+ * Same-origin path the committed fixture service answers on.
+ *
+ * `vite.config.ts` serves the fixture here in both `npm run dev` and
+ * `npm run preview`, and `src/main.ts` connects here whenever no live endpoint
+ * is configured. Keeping the path in one module is what makes the default lane
+ * work with no account, no key, and no third-party network call.
+ */
+export const FIXTURE_LAYER_PATH = "/fixture/rest/services/honua-demo/FeatureServer/0";

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

@@ -0,0 +1,113 @@
+import "maplibre-gl/dist/maplibre-gl.css";
+
+import { createHonua } from "@honua/sdk-js";
+import type { ConnectProtocolHint } from "@honua/sdk-js";
+import { maplibreRenderer } from "@honua/sdk-js/runtime";
+import * as maplibregl from "maplibre-gl";
+
+import { FIXTURE_LAYER_PATH } from "./fixture-endpoint.js";
+import "./styles.css";
+
+/** Offline basemap: the starter never fetches third-party tiles on its default lane. */
+const BASEMAP_STYLE = {
+  version: 8,
+  sources: {},
+  layers: [{ id: "background", type: "background", paint: { "background-color": "#0e1a17" } }],
+};
+
+const MAP_OPTIONS = { center: [-157.873, 21.2985], zoom: 11.4, attributionControl: false };
+
+/** Bounded row budget. Honua never mounts a truncated result silently. */
+const MAX_FEATURES = 250;
+
+const configuredEndpoint = import.meta.env.VITE_HONUA_ENDPOINT?.trim();
+const configuredProtocol = import.meta.env.VITE_HONUA_PROTOCOL?.trim();
+
+const endpoint =
+  configuredEndpoint && configuredEndpoint.length > 0
+    ? configuredEndpoint
+    : new URL(FIXTURE_LAYER_PATH, window.location.origin).toString();
+const protocol = (
+  configuredProtocol && configuredProtocol.length > 0 ? configuredProtocol : "geoservices-feature-service"
+) as ConnectProtocolHint;
+const dataLane = configuredEndpoint && configuredEndpoint.length > 0 ? "Live endpoint" : "Committed fixture";
+
+function element(id: string): HTMLElement {
+  const found = document.getElementById(id);
+  if (!found) throw new Error(`Missing #${id} element`);
+  return found;
+}
+
+function fact(name: string, value: string): void {
+  element(`fact-${name}`).textContent = value;
+}
+
+function stage(name: string, state: "running" | "done" | "failed", detail: string): void {
+  const item = document.querySelector<HTMLElement>(`[data-stage="${name}"]`);
+  if (!item) return;
+  item.dataset["state"] = state;
+  const label = item.querySelector<HTMLElement>(".stage-state");
+  if (label) label.textContent = detail;
+}
+
+async function run(): Promise<void> {
+  fact("mode", dataLane);
+  fact("endpoint", endpoint);
+
+  const honua = createHonua();
+  try {
+    stage("connect", "running", "connecting");
+    const connection = await honua.connect(
+      { url: endpoint, protocol },
+      { authorizationScopeFingerprint: "anonymous-public" },
+    );
+    stage("connect", "done", "connected");
+
+    stage("inspect", "running", "discovering");
+    const inspection = await connection.inspect();
+    const sourceId = inspection.defaultSourceId ?? inspection.sources[0]?.descriptor.id;
+    if (!sourceId) throw new Error("The endpoint advertised no queryable source.");
+    fact("protocol", inspection.protocol);
+    fact("source", sourceId);
+    stage("inspect", "done", `${inspection.sources.length} source(s)`);
+
+    stage("explain", "running", "planning");
+    const plan = await connection.explain(
+      {
+        returnGeometry: true,
+        pagination: { limit: MAX_FEATURES },
+        ...(inspection.protocol === "geoservices-feature-service" ? { outSr: 4326 } : {}),
+      },
+      { sourceId },
+    );
+    stage("explain", "done", "plan accepted");
+
+    stage("query", "running", "executing");
+    const result = await connection.query(plan);
+    fact("features", `${result.features.length}${result.exceededTransferLimit ? " (truncated)" : ""}`);
+    stage("query", "done", `${result.features.length} feature(s)`);
+
+    stage("mount", "running", "rendering");
+    // A selector or element target makes the SDK own the map's lifecycle; pass
+    // an existing `maplibregl.Map` instead to keep ownership in the app.
+    const mounted = await connection.mount(element("map"), {
+      renderer: maplibreRenderer(maplibregl),
+      query: plan,
+      sourceId,
+      style: BASEMAP_STYLE,
+      rendererOptions: { mapOptions: MAP_OPTIONS },
+    });
+    await mounted.ready;
+    stage("mount", "done", "mounted");
+    element("status").textContent = "The accepted plan is mounted. Every stage above ran through the public SDK API.";
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    element("status").textContent = `The workflow stopped: ${message}`;
+    for (const item of document.querySelectorAll<HTMLElement>("[data-stage]")) {
+      if (item.dataset["state"] === "running") stage(item.dataset["stage"] ?? "", "failed", "failed");
+    }
+    await honua.dispose();
+  }
+}
+
+void run();

package/templates/vanilla-ts/src/styles.css

@@ -0,0 +1,149 @@
+:root {
+  --surface: #f6f7f5;
+  --panel: #ffffff;
+  --ink: #10201b;
+  --muted: #5c6b66;
+  --line: #d9e0dc;
+  --accent: #0f766e;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --surface: #0b1210;
+    --panel: #111a17;
+    --ink: #e8f0ec;
+    --muted: #93a49e;
+    --line: #23322c;
+    --accent: #5eead4;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--surface);
+  color: var(--ink);
+  font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+.app {
+  display: grid;
+  grid-template-columns: minmax(280px, 360px) 1fr;
+  gap: 16px;
+  padding: 16px;
+  height: 100vh;
+}
+
+@media (max-width: 820px) {
+  .app {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto minmax(320px, 1fr);
+    height: auto;
+  }
+}
+
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 20px;
+  overflow-y: auto;
+}
+
+.eyebrow {
+  margin: 0;
+  color: var(--accent);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.title {
+  margin: 6px 0 12px;
+  font-size: 18px;
+  line-height: 1.3;
+}
+
+.status {
+  margin: 0 0 16px;
+  color: var(--muted);
+}
+
+.stages {
+  list-style: none;
+  margin: 0 0 20px;
+  padding: 0;
+  display: grid;
+  gap: 6px;
+}
+
+.stages li {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  font-size: 13px;
+}
+
+.stages li[data-state="running"] {
+  border-color: var(--accent);
+}
+
+.stages li[data-state="done"] .stage-state {
+  color: var(--accent);
+}
+
+.stages li[data-state="failed"] .stage-state {
+  color: #dc2626;
+}
+
+.stage-state {
+  color: var(--muted);
+}
+
+.facts {
+  display: grid;
+  gap: 8px;
+  margin: 0 0 16px;
+}
+
+.facts div {
+  display: grid;
+  grid-template-columns: 96px 1fr;
+  gap: 10px;
+  font-size: 13px;
+}
+
+.facts dt {
+  color: var(--muted);
+}
+
+.facts dd {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+.hint {
+  margin: 0;
+  color: var(--muted);
+  font-size: 13px;
+}
+
+code {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+  font-size: 12px;
+}
+
+.map {
+  min-height: 360px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  overflow: hidden;
+}

package/templates/vanilla-ts/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "allowSyntheticDefaultImports": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"]
+}

package/templates/vanilla-ts/vite.config.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
+
+import { type Plugin, defineConfig } from "vite";
+
+import { FIXTURE_LAYER_PATH } from "./src/fixture-endpoint.js";
+
+function fixtureDocument(name: string): string {
+  return readFileSync(fileURLToPath(new URL(`./fixtures/${name}`, import.meta.url)), "utf8");
+}
+
+/**
+ * Deterministic, offline GeoServices FeatureServer fixture.
+ *
+ * The starter's green path must never depend on a third-party endpoint, so the
+ * dev and preview servers answer the two routes the SDK's GeoServices adapter
+ * needs: the layer description and its bounded query. Point
+ * `VITE_HONUA_ENDPOINT` at a real service to run the same code against live data.
+ */
+function honuaFixtureService(): Plugin {
+  const layer = fixtureDocument("layer.json");
+  const features = fixtureDocument("features.json");
+  const middleware = (request: IncomingMessage, response: ServerResponse, next: () => void): void => {
+    const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+    let body: string | undefined;
+    if (pathname === FIXTURE_LAYER_PATH) body = layer;
+    else if (pathname === `${FIXTURE_LAYER_PATH}/query`) body = features;
+    if (body === undefined) {
+      next();
+      return;
+    }
+    response.setHeader("content-type", "application/json; charset=utf-8");
+    response.setHeader("cache-control", "no-store");
+    response.end(body);
+  };
+  return {
+    name: "honua-fixture-service",
+    configureServer(server) {
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [honuaFixtureService()],
+});

package/templates.manifest.json

@@ -0,0 +1,61 @@
+{
+  "format": "honua.sdk.create-honua-app-templates.v1",
+  "schemaVersion": 1,
+  "sdk": {
+    "package": "@honua/sdk-js",
+    "version": "0.1.2-beta.0"
+  },
+  "repository": {
+    "owner": "honua-io",
+    "name": "honua-sdk-js",
+    "branch": "trunk"
+  },
+  "playgroundProviders": [
+    {
+      "id": "stackblitz",
+      "title": "StackBlitz",
+      "urlTemplate": "https://stackblitz.com/github/{owner}/{repository}/tree/{branch}/{path}"
+    },
+    {
+      "id": "codesandbox",
+      "title": "CodeSandbox",
+      "urlTemplate": "https://codesandbox.io/s/github/{owner}/{repository}/tree/{branch}/{path}"
+    }
+  ],
+  "templates": [
+    {
+      "id": "vanilla-ts",
+      "title": "Vanilla TypeScript",
+      "summary": "Vite + TypeScript app that connects to an endpoint, explains a bounded query, and mounts the accepted plan on MapLibre.",
+      "path": "packages/create-honua-app/templates/vanilla-ts",
+      "entryFile": "src/main.ts",
+      "dataLane": "fixture",
+      "default": true,
+      "dependencies": [
+        "@honua/sdk-js",
+        "maplibre-gl",
+        "@bufbuild/protobuf",
+        "@connectrpc/connect",
+        "@connectrpc/connect-web"
+      ]
+    },
+    {
+      "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.",
+      "path": "packages/create-honua-app/templates/react-ts",
+      "entryFile": "src/App.tsx",
+      "dataLane": "fixture",
+      "default": false,
+      "dependencies": [
+        "@honua/sdk-js",
+        "maplibre-gl",
+        "react",
+        "react-dom",
+        "@bufbuild/protobuf",
+        "@connectrpc/connect",
+        "@connectrpc/connect-web"
+      ]
+    }
+  ]
+}