create-zudo-doc 0.1.0

package/templates/base/scripts/run-b4push.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# b4push — local quality gate run before pushing.
+#
+# Step order (cheap → expensive):
+#   1. Type checking (zfb check)
+#   2. Build (zfb build)
+#   3. HTML validation (html-validate dist/**/*.html)
+#   4. Manual interactive smoke (operator-driven)
+#
+# Env overrides for non-interactive use:
+#   B4PUSH_SKIP_HTML_VALIDATE=1  — skip HTML validation (step 3)
+#   B4PUSH_SKIP_MANUAL_SMOKE=1   — skip the manual interactive smoke
+
+START_TIME=$(date +%s)
+FAILURES=()
+TOTAL_STEPS=4
+CURRENT_STEP=0
+
+step() {
+  CURRENT_STEP=$((CURRENT_STEP + 1))
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "▶ Step $CURRENT_STEP/$TOTAL_STEPS: $1"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+}
+
+pass() { echo "✅ $1"; }
+fail() { echo "❌ $1"; FAILURES+=("$1"); }
+skip() { echo "⏭  $1 (skipped)"; }
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+# ── Step 1: Type checking ─────────────────────────────
+step "Type checking (zfb check)"
+if (cd "$ROOT_DIR" && pnpm check); then
+  pass "Type checking passed"
+else
+  fail "Type checking"
+fi
+
+# ── Step 2: Build ─────────────────────────────────────
+step "Build (zfb build)"
+if (cd "$ROOT_DIR" && pnpm build); then
+  pass "Build passed"
+else
+  fail "Build"
+fi
+
+# ── Step 3: HTML validation ───────────────────────────
+step "HTML validation (html-validate)"
+if [[ "${B4PUSH_SKIP_HTML_VALIDATE:-}" == "1" ]]; then
+  skip "HTML validation (B4PUSH_SKIP_HTML_VALIDATE=1)"
+else
+  if (cd "$ROOT_DIR" && pnpm check:html); then
+    pass "HTML validation passed"
+  else
+    fail "HTML validation"
+  fi
+fi
+
+# ── Step 4: Manual interactive smoke ─────────────────
+step "Manual interactive smoke"
+if [[ "${B4PUSH_SKIP_MANUAL_SMOKE:-}" == "1" ]]; then
+  skip "Manual smoke (B4PUSH_SKIP_MANUAL_SMOKE=1)"
+else
+  cat <<'MANUAL'
+Run `pnpm preview` in another terminal and exercise:
+  • theme toggle (light/dark)
+  • mobile menu (narrow viewport)
+  • search dropdown (header search)
+  • code-block syntax highlighting
+
+Press [Enter] when all flows look healthy, or Ctrl-C to abort.
+MANUAL
+  if read -r _; then
+    pass "Manual smoke acknowledged"
+  else
+    fail "Manual smoke (aborted)"
+  fi
+fi
+
+# ── Summary ──────────────────────────────────────────
+END_TIME=$(date +%s)
+DURATION=$((END_TIME - START_TIME))
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  SUMMARY (${DURATION}s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ ${#FAILURES[@]} -eq 0 ]; then
+  echo "✅ All $TOTAL_STEPS checks passed (or skipped). Safe to push."
+  exit 0
+else
+  echo "❌ ${#FAILURES[@]} check(s) failed:"
+  for f in "${FAILURES[@]}"; do
+    echo "   - $f"
+  done
+  exit 1
+fi

package/templates/base/src/components/ai-chat-modal.tsx

@@ -0,0 +1,15 @@
+// W6A stub — no-op default export.
+//
+// The host (zudo-doc showcase) ships a full AI-chat modal island here. In
+// generated downstream projects the AI assistant is gated behind a future
+// settings flag; for now the file exists so unconditional page imports
+// (`pages/lib/_body-end-islands.tsx`) resolve, and the component renders
+// nothing. Wire a real implementation by replacing this file.
+import type { JSX } from "preact";
+
+function AiChatModal(): JSX.Element | null {
+  return null;
+}
+AiChatModal.displayName = "AiChatModal";
+
+export default AiChatModal;

package/templates/base/src/components/client-router-bootstrap.tsx

@@ -0,0 +1,14 @@
+// W6A stub — no-op default export.
+//
+// The host installs a tiny client-side router bootstrap that re-runs
+// island lifecycle code across zfb navigations. Generated projects ship
+// the no-op so unconditional page imports (`pages/lib/_body-end-islands`)
+// resolve without dragging the routing bridge into every scaffold.
+import type { JSX } from "preact";
+
+function ClientRouterBootstrap(): JSX.Element | null {
+  return null;
+}
+ClientRouterBootstrap.displayName = "ClientRouterBootstrap";
+
+export default ClientRouterBootstrap;

package/templates/base/src/components/content/component-map.ts

@@ -0,0 +1,25 @@
+import { HeadingH2 } from './heading-h2';
+import { HeadingH3 } from './heading-h3';
+import { HeadingH4 } from './heading-h4';
+import { ContentParagraph } from './content-paragraph';
+import { ContentLink } from './content-link';
+import { ContentStrong } from './content-strong';
+import { ContentBlockquote } from './content-blockquote';
+import { ContentUl } from './content-ul';
+import { ContentOl } from './content-ol';
+import { ContentTable } from './content-table';
+import { ContentCode } from './content-code';
+
+export const htmlOverrides = {
+  h2: HeadingH2,
+  h3: HeadingH3,
+  h4: HeadingH4,
+  p: ContentParagraph,
+  a: ContentLink,
+  strong: ContentStrong,
+  blockquote: ContentBlockquote,
+  ul: ContentUl,
+  ol: ContentOl,
+  table: ContentTable,
+  code: ContentCode,
+};

package/templates/base/src/components/content/content-blockquote.tsx

@@ -0,0 +1,16 @@
+type Props = {
+  children?: React.ReactNode;
+  className?: string;
+  [key: string]: any;
+};
+
+export function ContentBlockquote({ children, className, ...rest }: Props) {
+  return (
+    <blockquote
+      className={`border-l-[3px] border-muted pl-hsp-lg text-muted italic${className ? ` ${className}` : ''}`}
+      {...rest}
+    >
+      {children}
+    </blockquote>
+  );
+}

package/templates/base/src/components/content/content-code.tsx

@@ -0,0 +1,117 @@
+import { SmartBreak as SmartBreakImpl } from '@/utils/smart-break';
+
+// Preact VNode vs React.ReactNode type mismatch under compat mode; cast so the
+// content override type-checks. Runtime is fine since @astrojs/preact compat is on.
+const SmartBreak = SmartBreakImpl as unknown as (props: {
+  children?: unknown;
+}) => any;
+
+type Props = {
+  children?: React.ReactNode;
+  className?: string;
+  [key: string]: any;
+};
+
+/**
+ * Override for inline `<code>` in MDX. Wraps text-only inline code with
+ * <SmartBreak> so that path/URL-like strings (e.g. `src/foo/bar.ts`) can
+ * break at delimiters on narrow viewports.
+ *
+ * Block code inside a fenced block is processed by Shiki, which emits a
+ * <code> element with class "language-*" containing a tree of <span>
+ * nodes (not a plain string). We detect those and render untouched so
+ * syntax highlighting is never disturbed.
+ *
+ * Astro 6 passes pure-text MDX children wrapped in a `StaticHtml` Preact
+ * component whose text lives in `props.value`, not as a string child.
+ * `extractText` unwraps that so the heuristic works regardless of MDX's
+ * internal wrapping.
+ */
+export function ContentCode({ children, className, ...rest }: Props) {
+  const isShikiBlock =
+    typeof className === 'string' && /(^|\s)language-/.test(className);
+
+  const textFromChildren = isShikiBlock ? null : extractText(children);
+
+  if (textFromChildren === null) {
+    return (
+      <code className={className} {...rest}>
+        {children}
+      </code>
+    );
+  }
+
+  return (
+    <code className={className} {...rest}>
+      <SmartBreak>{textFromChildren}</SmartBreak>
+    </code>
+  );
+}
+
+/**
+ * Walk a React/Preact children value and return a concatenated plain
+ * string when the entire subtree is text-only. Returns null if any
+ * non-text node (other than the StaticHtml wrapper Astro uses for pure
+ * text MDX content) is found — that signals inline markup inside the
+ * code span and means we must not inject <wbr>.
+ */
+function extractText(children: unknown): string | null {
+  if (typeof children === 'string') return children;
+  if (typeof children === 'number') return String(children);
+  // Only accept a single VNode whose `props.value` is text (the Astro
+  // StaticHtml wrapper used for pure-text MDX children). Deliberately do
+  // NOT recurse into arbitrary VNode trees — that would match Shiki's
+  // <span>-based block code output and inject <wbr> into syntax-highlighted
+  // tokens, breaking block code rendering.
+  if (children && typeof children === 'object' && !Array.isArray(children)) {
+    const v = children as { props?: { value?: unknown } };
+    if (v.props && v.props.value != null) {
+      if (
+        typeof v.props.value === 'string' ||
+        v.props.value instanceof String ||
+        (typeof v.props.value === 'object' && typeof (v.props.value as object).toString === 'function')
+      ) {
+        const s = String(v.props.value);
+        if (!s || s.startsWith('[object')) return null;
+        // Shiki block-code output also arrives as a StaticHtml wrapper, but
+        // its value is escaped HTML (e.g. "&lt;span class=...&gt;"). Inline
+        // code's value is the plain text of the backtick span (no HTML
+        // markup). If the value looks like HTML, refuse to unwrap — the
+        // block path below falls through to a plain <code> passthrough.
+        if (looksLikeHtmlMarkup(s)) return null;
+        return decodeEntities(s);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect whether a string is the HTML-escaped rendering of a Shiki block
+ * (with nested <span> tokens) rather than the plain text of an inline
+ * `<code>` span. The presence of an escaped HTML-tag opener (`&lt;span`,
+ * `&lt;code`, etc.) is a reliable signal; plain URL/path inline code
+ * never contains those escaped sequences.
+ */
+function looksLikeHtmlMarkup(s: string): boolean {
+  return /&lt;(span|code|pre|div|br|i|b|em|strong)\b/i.test(s) || /<(span|code|pre)\s/i.test(s);
+}
+
+/**
+ * Minimal HTML entity decoder for the set MDX produces for inline text
+ * (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`, numeric). Keeps the
+ * result visually identical to the authored source so downstream
+ * SmartBreak operates on the original characters.
+ */
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/gi, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+    .replace(/&amp;/g, '&');
+}

package/templates/base/src/components/content/content-link.tsx

@@ -0,0 +1,83 @@
+import { SmartBreak as SmartBreakBase } from '../../utils/smart-break';
+
+// SmartBreak is defined with Preact's VNode return type, but content
+// components type children as React.ReactNode. Cast to a React-compatible
+// signature; at runtime Preact compat unifies the two.
+const SmartBreak = SmartBreakBase as unknown as (props: {
+  children?: React.ReactNode;
+}) => React.ReactElement;
+
+type Props = {
+  href?: string;
+  className?: string;
+  children?: React.ReactNode;
+  [key: string]: any;
+};
+
+export function ContentLink({ href, className, children, ...rest }: Props) {
+  // Block links and hash-links (heading anchors) should render without content link styling
+  const classes = className ? className.split(' ') : [];
+  if (classes.includes('block') || classes.includes('hash-link')) {
+    return (
+      <a href={href} className={className} {...rest}>
+        {children}
+      </a>
+    );
+  }
+
+  // Astro 6 wraps pure-text MDX children in a `StaticHtml` Preact component
+  // whose text lives in `props.value`, not as a direct string child. Unwrap
+  // when possible so path-like text gets smart-break treatment.
+  const textFromChildren = extractText(children);
+  const content =
+    textFromChildren !== null ? (
+      <SmartBreak>{textFromChildren}</SmartBreak>
+    ) : (
+      children
+    );
+
+  return (
+    <a
+      href={href}
+      className={`text-accent underline hover:text-accent-hover${className ? ` ${className}` : ''}`}
+      {...rest}
+    >
+      {content}
+    </a>
+  );
+}
+
+function extractText(children: unknown): string | null {
+  if (typeof children === 'string') return children;
+  if (typeof children === 'number') return String(children);
+  // Only accept a single StaticHtml-like VNode (Astro's wrapper for pure-text
+  // MDX children). Arrays or VNodes with inline markup indicate mixed content
+  // that must not be flattened through SmartBreak.
+  if (children && typeof children === 'object' && !Array.isArray(children)) {
+    const v = children as { props?: { value?: unknown } };
+    if (v.props && v.props.value != null) {
+      if (
+        typeof v.props.value === 'string' ||
+        v.props.value instanceof String ||
+        (typeof v.props.value === 'object' && typeof (v.props.value as object).toString === 'function')
+      ) {
+        const s = String(v.props.value);
+        if (s && !s.startsWith('[object')) return decodeEntities(s);
+      }
+    }
+  }
+  return null;
+}
+
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/gi, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+    .replace(/&amp;/g, '&');
+}

package/templates/base/src/components/content/content-ol.tsx

@@ -0,0 +1,19 @@
+type Props = {
+  children?: React.ReactNode;
+  className?: string;
+  [key: string]: any;
+};
+
+// 2em indent: enough room for 2-digit markers like "66." (#244)
+// Inline style — Tailwind v4 does not generate arbitrary values from these TSX files
+export function ContentOl({ children, className, ...rest }: Props) {
+  return (
+    <ol
+      {...rest}
+      className={className || undefined}
+      style={{ paddingLeft: '2em', listStyleType: 'decimal' }}
+    >
+      {children}
+    </ol>
+  );
+}

package/templates/base/src/components/content/content-paragraph.tsx

@@ -0,0 +1,10 @@
+type Props = {
+  children?: React.ReactNode;
+  [key: string]: any;
+};
+
+// Passthrough: no custom styles needed for <p> (inherits from .zd-content base).
+// Override claimed to enable future Tailwind utilities without CSS cascade conflicts.
+export function ContentParagraph({ children, ...rest }: Props) {
+  return <p {...rest}>{children}</p>;
+}

package/templates/base/src/components/content/content-strong.tsx

@@ -0,0 +1,16 @@
+type Props = {
+  children?: React.ReactNode;
+  className?: string;
+  [key: string]: any;
+};
+
+export function ContentStrong({ children, className, ...rest }: Props) {
+  return (
+    <strong
+      className={`font-bold text-fg${className ? ` ${className}` : ''}`}
+      {...rest}
+    >
+      {children}
+    </strong>
+  );
+}

package/templates/base/src/components/content/content-table.tsx

@@ -0,0 +1,18 @@
+type Props = {
+  children?: React.ReactNode;
+  className?: string;
+  [key: string]: any;
+};
+
+export function ContentTable({ children, className, ...rest }: Props) {
+  return (
+    <div className="overflow-x-auto">
+      <table
+        className={`w-full border-collapse text-small${className ? ` ${className}` : ''}`}
+        {...rest}
+      >
+        {children}
+      </table>
+    </div>
+  );
+}

package/templates/base/src/components/content/content-ul.tsx

@@ -0,0 +1,18 @@
+type Props = {
+  children?: React.ReactNode;
+  className?: string;
+  [key: string]: any;
+};
+
+// 2em indent via inline style — Tailwind v4 does not generate arbitrary values from these TSX files (#244)
+export function ContentUl({ children, className, ...rest }: Props) {
+  return (
+    <ul
+      {...rest}
+      className={className || undefined}
+      style={{ paddingLeft: '2em', listStyleType: 'disc' }}
+    >
+      {children}
+    </ul>
+  );
+}

package/templates/base/src/components/content/heading-h2.tsx

@@ -0,0 +1,26 @@
+import type { CSSProperties } from 'react';
+import type { ComponentChildren } from 'preact';
+
+type Props = {
+  id?: string;
+  className?: string;
+  children?: ComponentChildren;
+  [key: string]: any;
+};
+
+export function HeadingH2({ id, children, className, ...rest }: Props) {
+  return (
+    <h2
+      id={id}
+      className={`text-title font-bold leading-tight pt-vsp-sm border-t-[3px] border-transparent${className ? ` ${className}` : ''}`}
+      style={
+        {
+          borderImage: 'linear-gradient(to right, var(--color-fg), transparent) 1',
+        } as CSSProperties
+      }
+      {...rest}
+    >
+      {children}
+    </h2>
+  );
+}

package/templates/base/src/components/content/heading-h3.tsx

@@ -0,0 +1,26 @@
+import type { CSSProperties } from 'react';
+import type { ComponentChildren } from 'preact';
+
+type Props = {
+  id?: string;
+  className?: string;
+  children?: ComponentChildren;
+  [key: string]: any;
+};
+
+export function HeadingH3({ id, children, className, ...rest }: Props) {
+  return (
+    <h3
+      id={id}
+      className={`text-body font-bold leading-snug pt-vsp-xs border-t-[2px] border-transparent${className ? ` ${className}` : ''}`}
+      style={
+        {
+          borderImage: 'linear-gradient(to right, var(--color-muted), transparent) 1',
+        } as CSSProperties
+      }
+      {...rest}
+    >
+      {children}
+    </h3>
+  );
+}

package/templates/base/src/components/content/heading-h4.tsx

@@ -0,0 +1,26 @@
+import type { CSSProperties } from 'react';
+import type { ComponentChildren } from 'preact';
+
+type Props = {
+  id?: string;
+  className?: string;
+  children?: ComponentChildren;
+  [key: string]: any;
+};
+
+export function HeadingH4({ id, children, className, ...rest }: Props) {
+  return (
+    <h4
+      id={id}
+      className={`text-body font-semibold leading-snug pt-vsp-xs border-t border-transparent${className ? ` ${className}` : ''}`}
+      style={
+        {
+          borderImage: 'linear-gradient(to right, var(--color-muted), transparent) 1',
+        } as CSSProperties
+      }
+      {...rest}
+    >
+      {children}
+    </h4>
+  );
+}

package/templates/base/src/components/design-token-panel-bootstrap.tsx

@@ -0,0 +1,15 @@
+// W6A stub — no-op default Preact wrapper.
+//
+// When the designTokenPanel feature is enabled, the feature template
+// overwrites this file with the real wrapper that side-effect-imports
+// `@/lib/design-token-panel-bootstrap` (which calls configurePanel and
+// mounts zdtp). Generated projects without the feature ship the no-op
+// so the unconditional `pages/lib/_body-end-islands` import resolves.
+import type { JSX } from "preact";
+
+function DesignTokenPanelBootstrap(): JSX.Element | null {
+  return null;
+}
+DesignTokenPanelBootstrap.displayName = "DesignTokenPanelBootstrap";
+
+export default DesignTokenPanelBootstrap;

package/templates/base/src/components/desktop-sidebar-toggle.tsx

@@ -0,0 +1,15 @@
+// W6A stub — no-op default export.
+//
+// When the sidebarToggle feature is enabled, the feature template
+// overwrites this file with the real desktop sidebar-toggle island.
+// Generated projects without the feature ship the no-op so the
+// unconditional `pages/lib/_body-end-islands` (or sidebar wrapper)
+// import resolves at typecheck time.
+import type { JSX } from "preact";
+
+function DesktopSidebarToggle(): JSX.Element | null {
+  return null;
+}
+DesktopSidebarToggle.displayName = "DesktopSidebarToggle";
+
+export default DesktopSidebarToggle;

package/templates/base/src/components/doc-history.tsx

@@ -0,0 +1,18 @@
+// W6A stub — no-op default + DocHistory named exports.
+//
+// When the docHistory feature is enabled, the feature template
+// overwrites this file with the real island. Generated projects
+// without the feature ship the no-op so the unconditional
+// `pages/lib/_doc-history-area` import resolves. The host module also
+// exposes `DocHistory` as a named export, so the stub mirrors both
+// shapes to keep the import surface stable.
+import type { JSX } from "preact";
+
+function DocHistoryComponent(): JSX.Element | null {
+  return null;
+}
+DocHistoryComponent.displayName = "DocHistory";
+
+export default DocHistoryComponent;
+
+export const DocHistory = DocHistoryComponent;

package/templates/base/src/components/html-preview/highlighted-code.tsx

@@ -0,0 +1,74 @@
+import { useEffect, useState } from "preact/compat";
+import type { HighlighterCore } from "shiki";
+
+let highlighterPromise: Promise<HighlighterCore> | null = null;
+
+function getHighlighter(): Promise<HighlighterCore> {
+  if (!highlighterPromise) {
+    highlighterPromise = import("shiki")
+      .then(({ createHighlighter }) =>
+        createHighlighter({
+          themes: ["catppuccin-latte", "vitesse-dark"],
+          langs: ["html", "css", "javascript"],
+        }),
+      )
+      .catch((err) => {
+        // Clear cached rejection so next call retries
+        highlighterPromise = null;
+        throw err;
+      });
+  }
+  return highlighterPromise;
+}
+
+interface HighlightedCodeProps {
+  code: string;
+  language: string;
+}
+
+export default function HighlightedCode({
+  code,
+  language,
+}: HighlightedCodeProps) {
+  const [html, setHtml] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    getHighlighter()
+      .then((highlighter) => {
+        if (cancelled) return;
+        const lang = highlighter.getLoadedLanguages().includes(language)
+          ? language
+          : "text";
+        const result = highlighter.codeToHtml(code, {
+          lang,
+          themes: { light: "catppuccin-latte", dark: "vitesse-dark" },
+          defaultColor: false,
+        });
+        setHtml(result);
+      })
+      .catch(() => {
+        // Shiki failed to load — keep showing the plain-text fallback
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [code, language]);
+
+  if (!html) {
+    return (
+      <pre className="m-0 p-hsp-md bg-code-bg text-caption leading-relaxed overflow-x-auto">
+        <code className="font-mono whitespace-pre">
+          {code}
+        </code>
+      </pre>
+    );
+  }
+
+  return (
+    <div
+      className="zd-html-preview-code"
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+}