zero-query 1.2.4 → 1.2.6

package/README.md

@@ -43,20 +43,32 @@
 
 The fastest way to develop with zQuery is via the built-in **CLI dev server** with **live-reload**. It serves your ES modules as-is and automatically resolves the library - no manual downloads required.
 
+Pick a scaffold flavor — every variant auto-installs, auto-starts, and opens your browser:
+
 ```bash
-npx zero-query create my-app
+# Default: full sidebar layout, router, demo components, responsive styles
+npx zero-query create my-app                    # → http://localhost:3100
+
+# Minimal: lightweight 3-page starter
+npx zero-query create my-app --minimal          # → http://localhost:3100   (alias: -m)
+
+# SSR: Node.js server-side rendering project
+npx zero-query create my-app --ssr              # → http://localhost:3000   (alias: -s)
+
+# WebRTC: one-page video room backed by zero-server
+npx zero-query create my-app --webrtc-demo      # → http://localhost:3000   (alias: -w)
 ```
 
-That's it. One command scaffolds the project, installs dependencies, starts the dev server, and opens your browser to <http://localhost:3100>. To restart later:
+That's it. One command scaffolds the project, installs dependencies, starts the server, and opens the browser. To restart later:
 
 ```bash
 cd my-app
 npm run dev      # or: npm start
 ```
 
-> **Tip:** Stay in the project root (where `node_modules` lives) instead of `cd`-ing into `my-app`. This keeps `index.d.ts` accessible to your IDE for full type/intellisense support.
+> **Tip:** For the default and minimal variants, you can stay in the project root (where `node_modules` lives) instead of `cd`-ing into `my-app`. This keeps `index.d.ts` accessible to your IDE for full type/intellisense support.
 
-The `create` command generates a ready-to-run project with a sidebar layout, router, multiple components (including folder components with external templates and styles), and responsive styles. Use `--minimal` (or `-m`) for a lightweight 3-page starter. Use `--ssr` (or `-s`) for a Node.js server-side rendering project (auto-launches on port 3000). Use `--webrtc-demo` (or `-w`) for a one-page video room backed by [zero-server](https://github.com/tonywied17/zero-server) (also port 3000). Every variant auto-installs, auto-starts, and opens the browser. The dev server watches for file changes, hot-swaps CSS in-place, full-reloads on other changes, and handles SPA fallback routing.
+The default scaffold ships a sidebar layout, router, multiple components (including folder components with external templates and styles), and responsive styles. The SSR variant runs a Node.js server that renders pages to HTML strings. The WebRTC variant is wired to [zero-server](https://github.com/tonywied17/zero-server) for signaling + TURN. The dev server watches for file changes, hot-swaps CSS in-place, full-reloads on other changes, and handles SPA fallback routing.
 
 #### Error Overlay
 
@@ -235,6 +247,24 @@ my-app/                          ← SSR scaffold (npx zquery create my-app --ss
 
 Components in `app/components/` export plain definition objects - the client registers them with `$.component()`, the server with `app.component()`. The scaffold includes a blog with param-based routing (`/blog/:slug`), per-route SEO metadata, JSON API endpoints (`/api/posts`), and `window.__SSR_DATA__` hydration. The `--ssr` flag handles everything automatically - installs dependencies, starts the server at `http://localhost:3000`, and opens the browser.
 
+Use `--webrtc-demo` (`-w`) for a one-page video room backed by [zero-server](https://github.com/tonywied17/zero-server):
+
+```
+my-app/                          ← webrtc scaffold (npx zquery create my-app --webrtc-demo)
+  index.html                     ← single-page video room shell
+  global.css
+  package.json                   ← declares @zero-server/sdk + @zero-server/webrtc deps
+  app/
+    app.js                       ← boots the room component
+    components/
+      video-room.js              ← join controls, peer grid, z-stream bindings
+  server/
+    index.js                     ← signaling + static server (zero-server-backed)
+  assets/
+```
+
+The signaling server is a thin wrapper around `@zero-server/webrtc` that issues join tokens, relays SDP/ICE, and serves the static client. Set `WEBRTC_JWT_SECRET`, `TURN_SECRET`, and `TURN_URLS` env vars to enable TURN. The `--webrtc-demo` flag installs all deps (zQuery + the two `@zero-server` packages), starts the signaling + static server at `http://localhost:3000`, and opens the browser.
+
 - One component per file inside `components/`.
 - Names **must contain a hyphen** (Web Component convention): `home-page`, `app-counter`, etc.
 - Components with external templates or styles can use a subfolder (e.g. `contacts/contacts.js` + `contacts.html` + `contacts.css`).

package/cli/commands/build-api.js

@@ -220,9 +220,17 @@ function htmlToMarkdown(html) {
   md = md.replace(/<div class="file-tree">[\s\S]*?<\/div>(?:\s*<\/div>)*/g, '');
 
   // ---- Pass 5: Convert headings ----
-  md = md.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/g, (_, c) => '\n## ' + unesc(inlineMd(c)).trim() + '\n');
-  md = md.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/g, (_, c) => '\n### ' + unesc(inlineMd(c)).trim() + '\n');
-  md = md.replace(/<h4[^>]*>([\s\S]*?)<\/h4>/g, (_, c) => '\n#### ' + unesc(inlineMd(c)).trim() + '\n');
+  // Preserve `id` attributes by emitting an explicit HTML anchor before the
+  // heading so cross-section duplicate titles (e.g. "Overview") still resolve
+  // to unique anchors in the rendered Markdown TOC.
+  const headingRepl = (level) => (_, attrs, c) => {
+    const idMatch = /\bid="([^"]+)"/.exec(attrs || '');
+    const anchor  = idMatch ? `<a id="${idMatch[1]}"></a>\n` : '';
+    return '\n' + anchor + '#'.repeat(level) + ' ' + unesc(inlineMd(c)).trim() + '\n';
+  };
+  md = md.replace(/<h2([^>]*)>([\s\S]*?)<\/h2>/g, headingRepl(2));
+  md = md.replace(/<h3([^>]*)>([\s\S]*?)<\/h3>/g, headingRepl(3));
+  md = md.replace(/<h4([^>]*)>([\s\S]*?)<\/h4>/g, headingRepl(4));
 
   // ---- Pass 6: Convert lists ----
   md = md.replace(/<ul>([\s\S]*?)<\/ul>/g, (_, content) => {
@@ -298,14 +306,19 @@ function slugify(text) {
 function buildToc(sections) {
   const lines = [];
   for (const section of sections) {
-    // Get the section title from the first <h2> in content
+    // Get the section title from the first <h2> in content, preferring an
+    // explicit `id` attribute when present so the TOC link is stable and
+    // unique across sections.
     const html = section.content();
-    const h2Match = html.match(/<h2[^>]*>([\s\S]*?)<\/h2>/);
-    const title = h2Match ? unesc(inlineMd(h2Match[1])).trim() : section.label;
-    lines.push(`- [${title}](#${slugify(title)})`);
+    const h2Match = html.match(/<h2([^>]*)>([\s\S]*?)<\/h2>/);
+    const title  = h2Match ? unesc(inlineMd(h2Match[2])).trim() : section.label;
+    const h2Id   = h2Match && /\bid="([^"]+)"/.exec(h2Match[1] || '');
+    const anchor = h2Id ? h2Id[1] : (section.id || slugify(title));
+    lines.push(`- [${title}](#${anchor})`);
     for (const h of section.headings) {
       const hText = unesc(h.text);
-      lines.push(`  - [${hText}](#${slugify(hText)})`);
+      const hAnchor = h.id || slugify(hText);
+      lines.push(`  - [${hText}](#${hAnchor})`);
     }
   }
   return lines.join('\n');