@bytesbrains/weblocks 0.6.0 → 0.6.2

package/CATALOG.md

@@ -1,4 +1,4 @@
-# @bytesbrains/weblocks — Block Catalog (v0.6.0)
+# @bytesbrains/weblocks — Block Catalog (v0.6.2)
 
 The AI composes a `SiteManifest` (`{ meta, design, blocks[] }`) using **only** the block types below, then the engine validates + renders it to static HTML. This file is generated from the code (`npm run emit:catalog`) — do not edit by hand.
 

package/CHANGELOG.md

@@ -5,6 +5,34 @@ follows [semantic versioning](https://semver.org): the **block catalog** and the
 **`SiteManifest` shape** are the public contract — additive block/field changes
 are minor, breaking changes to either are major.
 
+## 0.6.2 — 2026-07-17
+
+Bug fix: in-page nav links now scroll.
+
+### Fixed
+- **In-page nav links now scroll (#26).** `renderSite` previously emitted sections
+  without ids, so `#about` / `#menu` / `#contact` resolved to nothing on every
+  generated site. It now emits a stable, de-duped anchor `id` on each content
+  section (a canonical slug — e.g. `contact-details` → `#contact`,
+  `services-catalogue` → `#services`, `testimonials` → `#reviews`), and `nav`
+  (plus its CTA) resolves links by `#hash`, label, or a common alias
+  (`Menu` → services, `Get in touch` → contact, …). External/relative links pass
+  through; unresolved links fall back to `#` (top), never a dead anchor. Chrome
+  and rhythm blocks get no anchor. **Render-side, so re-rendering an existing
+  manifest just works** — no manifest change needed.
+
+### Added
+- `slugify` exported (`'About Us!'` → `'about-us'`, folds diacritics).
+
+## 0.6.1 — 2026-07-16
+
+Docs only — no engine changes.
+
+### Added
+- A runnable **résumé example** (`npm run example:resume` → `resume-output.html`)
+  demonstrating the résumé pack + print-to-PDF end to end, and a README pointer
+  to it.
+
 ## 0.6.0 — 2026-07-16
 
 A résumé/CV builder, hero image banners, and favicons. Additive and

package/README.md

@@ -298,8 +298,9 @@ typed schema (no raw-HTML field), consumes shared tokens, renders totally
 npm install          # dev deps only (typescript, @types/node)
 npm run build        # tsc → lib/
 npm test             # block definition-of-done + engine invariants
-npm run example      # render a sample → example-output.html
-npm run emit:catalog # regenerate catalog.json + CATALOG.md from code
+npm run example         # render a sample landing page → example-output.html
+npm run example:resume  # render a live résumé/CV → resume-output.html (try its Download-PDF)
+npm run emit:catalog    # regenerate catalog.json + CATALOG.md from code
 ```
 
 Drive it end-to-end with a real model (dev harness — provider is env, not code):

package/catalog.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "package": "@bytesbrains/weblocks",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Block catalog for @bytesbrains/weblocks. Send this to the model as its API reference; it composes a SiteManifest ({ meta, design, blocks[] }) using ONLY these block types. The engine then validates and renders it.",
   "blockTypes": [
     "app-shell",

package/lib/anchors.d.ts

@@ -0,0 +1,11 @@
+import type { Block } from './types.js';
+export interface Anchors {
+    /** blockId → the anchor id emitted on its section (absent = skipped). */
+    idFor: Map<string, string>;
+    /** Resolve a nav/CTA link (by hash, label, or alias) to a working href. */
+    resolve(href: unknown, label?: string): string;
+}
+/** Assign a unique anchor id to each anchorable block and build a link resolver. */
+export declare function buildAnchors(blocks: Block[]): Anchors;
+/** Insert an anchor `id` into the first element of a block's rendered HTML. */
+export declare function injectAnchorId(html: string, id: string): string;

package/lib/anchors.js

@@ -0,0 +1,77 @@
+/**
+ * In-page anchors — makes nav links actually scroll (issue #26).
+ *
+ * `renderSite` emits sections without ids, so `#about` / `#menu` resolve to
+ * nothing. This module computes a stable, de-duped anchor id per content section
+ * (a canonical slug that can differ from the block's short CSS class, e.g.
+ * `contact-details` → `contact`, `services-catalogue` → `services`) and resolves
+ * a nav/CTA link — by its `#hash`, its label, or a common alias — to a real id.
+ * Chrome blocks (nav, app-shell, sidebar, announcement-bar) and pure rhythm
+ * blocks get no anchor. Unresolved links fall back to `#` (top), never a dead
+ * anchor. Render-side, so re-rendering an existing manifest just works.
+ */
+import { slugify } from './schema.js';
+const SKIP = new Set(['nav', 'app-shell', 'sidebar', 'announcement-bar', 'divider', 'spacer']);
+/** Canonical anchor slug per block type (default = the type name). */
+const SECTION_SLUG = {
+    hero: 'home', 'hero-app': 'home', 'profile-header': 'home',
+    about: 'about',
+    'contact-details': 'contact', 'contact-form': 'contact',
+    'services-catalogue': 'services',
+    testimonials: 'reviews',
+    'blog-list': 'blog', 'blog-post': 'blog',
+    'video-gallery': 'videos',
+};
+/** Common nav-label slugs → the canonical section slug they mean. */
+const ALIAS = {
+    menu: 'services', catalog: 'services', catalogue: 'services', products: 'services', shop: 'services',
+    story: 'about', 'our-story': 'about', 'about-us': 'about', bio: 'about', 'who-we-are': 'about',
+    'get-in-touch': 'contact', 'contact-us': 'contact', 'reach-us': 'contact', reach: 'contact', hire: 'contact', 'hire-me': 'contact',
+    testimonials: 'reviews', feedback: 'reviews',
+    work: 'gallery', portfolio: 'gallery', photos: 'gallery',
+    questions: 'faq', help: 'faq',
+    plans: 'pricing', prices: 'pricing',
+};
+function sectionSlug(type) {
+    if (SKIP.has(type))
+        return null;
+    return SECTION_SLUG[type] ?? type;
+}
+/** Assign a unique anchor id to each anchorable block and build a link resolver. */
+export function buildAnchors(blocks) {
+    const idFor = new Map();
+    const ids = new Set(); // every emitted anchor id
+    const slugToId = new Map(); // canonical slug → first emitted id of that type
+    for (const b of blocks) {
+        const base = b && sectionSlug(b.type);
+        if (!base || !b.id)
+            continue;
+        let id = base;
+        for (let n = 2; ids.has(id); n++)
+            id = `${base}-${n}`; // de-dup repeats
+        ids.add(id);
+        idFor.set(b.id, id);
+        if (!slugToId.has(base))
+            slugToId.set(base, id);
+    }
+    // A slug → an existing anchor id: exact id (incl. de-duped like `features-2`),
+    // canonical slug, or a common alias. '' when nothing matches.
+    const lookup = (key) => (ids.has(key) ? key : slugToId.get(key) ?? slugToId.get(ALIAS[key] ?? '') ?? '');
+    const resolve = (href, label = '') => {
+        const raw = String(href ?? '').trim();
+        if (/^[a-z][a-z0-9+.-]*:/i.test(raw))
+            return raw; // scheme (http/mailto/tel/…) → external, untouched
+        if (raw && !raw.startsWith('#'))
+            return raw; // relative path/query → untouched
+        const key = slugify(raw.startsWith('#') && raw.length > 1 ? raw.slice(1) : label); // hash text, else label
+        if (!key || key === 'home' || key === 'top' || key === 'start')
+            return '#'; // Home/Top → page top
+        const id = lookup(key);
+        return id ? `#${id}` : '#'; // resolved anchor, else top (never a dead anchor)
+    };
+    return { idFor, resolve };
+}
+/** Insert an anchor `id` into the first element of a block's rendered HTML. */
+export function injectAnchorId(html, id) {
+    return html.replace(/^(\s*<[a-zA-Z][\w-]*)(\s|>)/, (_m, open, next) => `${open} id="${id}"${next}`);
+}

package/lib/blocks/nav.js

@@ -19,16 +19,19 @@ const css = `
 .blk-nav .links a:hover{color:var(--text)}
 .blk-nav .cta{background:var(--primary);color:var(--on-primary);padding:.5em 1.1em;border-radius:var(--radius);text-decoration:none;font-weight:600}
 `.trim();
-function render(config) {
+function render(config, _tokens, ctx) {
     const brand = config.brand;
     const sticky = config.sticky;
     const links = config.links ?? [];
     const cta = config.cta;
-    const linkHtml = links.map((l) => `<a href="${escapeAttr(sanitizeUrl(l.href))}">${escapeHtml(l.label)}</a>`).join('');
+    // Resolve in-page links to real section anchors (falls back to plain sanitize
+    // when rendered without a page context, e.g. a single block in isolation).
+    const href = (l) => escapeAttr(sanitizeUrl(ctx?.resolveLink ? ctx.resolveLink(l.href, l.label) : l.href));
+    const linkHtml = links.map((l) => `<a href="${href(l)}">${escapeHtml(l.label)}</a>`).join('');
     return `<nav class="blk-nav" data-sticky="${sticky ? 'true' : 'false'}" aria-label="Primary">
   <div class="wrap">
     <a class="brand" href="#">${escapeHtml(brand)}</a>
-    <div class="links">${linkHtml}${cta.label ? `<a class="cta" href="${escapeAttr(sanitizeUrl(cta.href))}">${escapeHtml(cta.label)}</a>` : ''}</div>
+    <div class="links">${linkHtml}${cta.label ? `<a class="cta" href="${href(cta)}">${escapeHtml(cta.label)}</a>` : ''}</div>
   </div>
 </nav>`;
 }

package/lib/index.d.ts

@@ -13,7 +13,7 @@ export { renderSite, type RenderOptions } from './render.js';
 export { NOOP_RUNTIME, pathRuntime, runtimeNeeds, type RuntimeAdapter, type RuntimeAction, type BlockRuntimeNeeds, } from './runtime.js';
 export { buildWebManifest, buildWebManifestJson, buildServiceWorker, emitPwa, type WebAppManifest, } from './pwa.js';
 export { validateBlock, validateManifest, type Validation } from './validate.js';
-export { parse, escapeHtml, escapeAttr, sanitizeUrl, type Field, type Schema, type ParseResult } from './schema.js';
+export { parse, escapeHtml, escapeAttr, sanitizeUrl, slugify, type Field, type Schema, type ParseResult } from './schema.js';
 export { renderMarkdown } from './markdown.js';
 export { catalog, catalogPrompt, type BlockCatalogEntry, type JsonSchema } from './catalog.js';
 export { applyOp, applyOps, type EditOp, type OpResult, type BatchResult } from './ops.js';

package/lib/index.js

@@ -5,7 +5,7 @@ export { renderSite } from './render.js';
 export { NOOP_RUNTIME, pathRuntime, runtimeNeeds, } from './runtime.js';
 export { buildWebManifest, buildWebManifestJson, buildServiceWorker, emitPwa, } from './pwa.js';
 export { validateBlock, validateManifest } from './validate.js';
-export { parse, escapeHtml, escapeAttr, sanitizeUrl } from './schema.js';
+export { parse, escapeHtml, escapeAttr, sanitizeUrl, slugify } from './schema.js';
 export { renderMarkdown } from './markdown.js';
 export { catalog, catalogPrompt } from './catalog.js';
 export { applyOp, applyOps } from './ops.js';

package/lib/registry.d.ts

@@ -16,6 +16,12 @@ export interface RenderContext {
     id: string;
     /** Host-provided runtime; `resolve` returns null when unwired (inert render). */
     runtime: RuntimeAdapter;
+    /**
+     * Resolve an in-page nav/CTA link (by `#hash`, label, or alias) to a working
+     * href against the page's section anchor ids. External/relative links pass
+     * through; unresolved links fall back to `#`. Used by navigation bricks.
+     */
+    resolveLink?: (href: unknown, label?: string) => string;
 }
 export interface BlockSpec {
     type: string;

package/lib/render.js

@@ -13,6 +13,7 @@ import { escapeAttr, escapeHtml, parse, sanitizeUrl } from './schema.js';
 import { getSpec, needsIsland, REGISTRY } from './registry.js';
 import { normalizeTokens, sectionOverrideCss, tokensToCss } from './tokens.js';
 import { NOOP_RUNTIME } from './runtime.js';
+import { buildAnchors, injectAnchorId } from './anchors.js';
 const RESET_CSS = `
 *,*::before,*::after{box-sizing:border-box}
 body{margin:0;font-family:var(--font);font-size:var(--fs-base);color:var(--text);background:var(--bg);line-height:1.5;-webkit-font-smoothing:antialiased}
@@ -25,14 +26,18 @@ img{max-width:100%}
 // un-stick fixed chrome, and avoid splitting entries across pages.
 const PRINT_CSS = `@media print{*{-webkit-print-color-adjust:exact;print-color-adjust:exact}[data-wl-noprint]{display:none!important}.blk-nav,.blk-app-shell,.blk-announcement-bar,.blk-sidebar{position:static!important}.blk-profile-header,.blk-experience .entry,.blk-skills .group,.blk-timeline li{break-inside:avoid}a[href]{text-decoration:none}@page{margin:1.4cm}}`;
 /** Render one block: normalize its config, then hand markup to the brick. */
-function renderBlock(block, manifest, runtime) {
+function renderBlock(block, manifest, runtime, anchors) {
     const spec = getSpec(block.type);
     if (!spec)
         return ''; // unknown type → skip (closed vocabulary; total)
     const { value } = parse(spec.schema, block.config ?? {});
     const tokens = normalizeTokens(manifest.design);
-    const ctx = { id: block.id, runtime };
+    const ctx = { id: block.id, runtime, resolveLink: anchors.resolve };
     let html = spec.render(value, tokens, ctx);
+    // In-page anchor: emit a stable id on the section so nav links can scroll to it.
+    const anchorId = anchors.idFor.get(block.id);
+    if (anchorId)
+        html = injectAnchorId(html, anchorId);
     // Opt-in per-section overrides: scope palette/radius/spacing as inherited CSS
     // vars on a wrapper (escaped for the style attribute).
     const style = sectionOverrideCss(block.overrides);
@@ -52,7 +57,8 @@ export function renderSite(manifest, options = {}) {
         .filter((s) => usedTypes.has(s.type) && s.css)
         .map((s) => s.css)
         .join('\n');
-    const body = blocks.map((b) => renderBlock(b, manifest, runtime)).filter(Boolean).join('\n');
+    const anchors = buildAnchors(blocks);
+    const body = blocks.map((b) => renderBlock(b, manifest, runtime, anchors)).filter(Boolean).join('\n');
     // Islands to hydrate. Static-only pages emit none.
     const islands = new Set();
     for (const b of blocks) {

package/lib/schema.d.ts

@@ -65,3 +65,9 @@ export declare function escapeAttr(s: unknown): string;
  * attribute context.
  */
 export declare function sanitizeUrl(url: unknown): string;
+/**
+ * A URL-fragment slug from arbitrary text: `'About Us!'` → `'about-us'`.
+ * Diacritics are folded (`résumé` → `resume`). Used for section anchor ids and
+ * nav in-page link resolution.
+ */
+export declare function slugify(s: unknown): string;

package/lib/schema.js

@@ -148,3 +148,18 @@ export function sanitizeUrl(url) {
         return '#';
     return s;
 }
+/**
+ * A URL-fragment slug from arbitrary text: `'About Us!'` → `'about-us'`.
+ * Diacritics are folded (`résumé` → `resume`). Used for section anchor ids and
+ * nav in-page link resolution.
+ */
+export function slugify(s) {
+    return String(s ?? '')
+        .normalize('NFKD').replace(/[̀-ͯ]/g, '') // fold accents
+        .toLowerCase()
+        .replace(/[^a-z0-9\s_-]/g, '') // drop other punctuation
+        .trim()
+        .replace(/[\s_]+/g, '-') // spaces/underscores → hyphen
+        .replace(/-+/g, '-') // collapse
+        .replace(/^-+|-+$/g, ''); // trim hyphens
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytesbrains/weblocks",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Block engine for AI-composable web apps — the AI composes a SiteManifest from a fixed block catalog; the engine validates and renders it to static HTML. Snap-together \"Lego\" web building blocks, shareable across repos.",
   "keywords": [
     "ai",
@@ -37,7 +37,7 @@
     "lib",
     "!lib/**/*.test.js",
     "!lib/**/*.test.d.ts",
-    "!lib/example.*",
+    "!lib/example*",
     "catalog.json",
     "CATALOG.md",
     "AGENT.md",
@@ -61,6 +61,7 @@
     "emit:catalog": "node scripts/emit-catalog.mjs",
     "test": "npm run build && node --test lib/*.test.js test/*.mjs",
     "example": "tsc -p tsconfig.json && node lib/example.js",
+    "example:resume": "tsc -p tsconfig.json && node lib/example-resume.js",
     "ai": "tsc -p tsconfig.json && node scripts/ai-run.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && npm run emit:catalog && npm test"