@vmz/vmz 0.0.1 → 0.0.3

package/dist/document-interactive.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Strip tags / collapse whitespace for search body text.
+ * @param {string} html
+ */
+export declare function htmlToSearchText(html: any): string;
+/**
+ * @param {{
+ * manifest: any,
+ * enriched: { byId: Map<string, any> },
+ * evidence: any,
+ * version?: string | null,
+ * }} opts
+ */
+export declare function buildDocumentSearch(opts: any): {
+    schema: string;
+    status: string;
+    version: any;
+    records: any[];
+};
+/**
+ * Island-only resume plan for document surfaces.
+ * @param {{
+ * evidence: any,
+ * searchHref?: string,
+ * fenceBodies?: Map<string, string>,
+ * }} opts
+ */
+export declare function buildDocumentIslands(opts: any): {
+    schema: string;
+    hydrate: string;
+    fullPageHydrate: boolean;
+    islands: {
+        name: string;
+        kind: string;
+        resume: string;
+        index: any;
+    }[];
+    status: string;
+};
+/**
+ * Relative href from an HTML page to a root artifact (posix).
+ * @param {string} htmlRel
+ * @param {string} artifactName
+ */
+export declare function artifactHrefFromHtml(htmlRel: any, artifactName: any): string;
+/**
+ * Stable map key for fence body lookup.
+ * @param {{ locale: string, pageKey: string, lineStart: number }} f
+ */
+export declare function fenceBodyKey(f: any): string;
+/**
+ * Collect fence bodies from analyzeMarkdown results for playground islands.
+ * @param {Map<string, { fences?: any[] }>} analyzedByPageId locale:pageKey → analyze result
+ * @param {any[]} pages manifest.pages
+ */
+export declare function collectFenceBodies(analyzedByPageId: any, pages: any): Map<any, any>;
+/**
+ * Render SSR island shells (no script — resume later).
+ * @param {{
+ * islands: any,
+ * searchIndexHref: string,
+ * pageKey: string,
+ * locale: string,
+ * }} opts
+ */
+export declare function renderIslandShellsHtml(opts: any): {
+    searchHtml: string;
+    playgroundHtml: any;
+};

package/dist/document-interactive.js

@@ -0,0 +1,254 @@
+// @ts-nocheck
+/**
+ * Document Interactive — search index + Island-only resume plan.
+ *
+ * Not a Doc IR: build artifacts + ResumeEntry-shaped island hosts.
+ * Static HTML stays no-JS readable; islands resume later, never full-page hydrate.
+ */
+import { DOCUMENT_ISLANDS_SCHEMA, DOCUMENT_SEARCH_SCHEMA } from './document-schema.js';
+import { parseFenceInfo } from './document-evidence.js';
+/**
+ * Strip tags / collapse whitespace for search body text.
+ * @param {string} html
+ */
+export function htmlToSearchText(html) {
+    return String(html || '')
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * @param {{
+ * manifest: any,
+ * enriched: { byId: Map<string, any> },
+ * evidence: any,
+ * version?: string | null,
+ * }} opts
+ */
+export function buildDocumentSearch(opts) {
+    const { manifest, enriched, evidence } = opts;
+    const version = opts.version ?? null;
+    /** @type {any[]} */
+    const records = [];
+    for (const page of manifest.pages || []) {
+        const id = `${page.identity.locale}:${page.identity.pageKey}`;
+        const info = enriched.byId.get(id);
+        if (!info)
+            continue;
+        const locale = page.identity.locale;
+        const pageKey = page.identity.pageKey;
+        const route = info.route || page.route;
+        const title = info.title || pageKey;
+        const text = htmlToSearchText(info.html);
+        const headings = (info.headings || []).map((h) => ({
+            id: h.id,
+            level: h.level,
+            text: h.text,
+        }));
+        const apiSymbolIds = (evidence?.apiRefs || [])
+            .filter((r) => r.locale === locale && r.pageKey === pageKey && r.status === 'ok')
+            .flatMap((r) => (r.matches || []).map((m) => m.chunkId || m.name))
+            .filter(Boolean);
+        records.push({
+            kind: 'page',
+            id: `page:${locale}:${pageKey}`,
+            locale,
+            pageKey,
+            route,
+            title,
+            text,
+            headings,
+            apiSymbolIds,
+            version,
+        });
+        for (const h of headings) {
+            records.push({
+                kind: 'heading',
+                id: `heading:${locale}:${pageKey}#${h.id}`,
+                locale,
+                pageKey,
+                route: `${route}#${h.id}`,
+                title: h.text,
+                text: h.text,
+                headingId: h.id,
+                headingLevel: h.level,
+                version,
+            });
+        }
+    }
+    for (const ref of evidence?.apiRefs || []) {
+        if (ref.status !== 'ok')
+            continue;
+        for (const m of ref.matches || []) {
+            const page = (manifest.pages || []).find((p) => p.identity.locale === ref.locale && p.identity.pageKey === ref.pageKey);
+            const info = page ? enriched.byId.get(`${ref.locale}:${ref.pageKey}`) : null;
+            records.push({
+                kind: 'api',
+                id: `api:${m.chunkId || m.name}`,
+                locale: ref.locale,
+                pageKey: ref.pageKey,
+                route: info?.route || null,
+                title: m.name || m.chunkId,
+                text: `${m.name || ''} ${m.chunkId || ''} ${(m.capabilities || []).join(' ')}`.trim(),
+                apiSymbolId: m.chunkId || m.name,
+                stableId: m.stableId || { kind: 'chunk', id: m.chunkId },
+                version,
+            });
+        }
+    }
+    return {
+        schema: DOCUMENT_SEARCH_SCHEMA,
+        status: records.length ? 'ready' : 'empty',
+        version,
+        records,
+    };
+}
+/**
+ * Island-only resume plan for document surfaces.
+ * @param {{
+ * evidence: any,
+ * searchHref?: string,
+ * fenceBodies?: Map<string, string>,
+ * }} opts
+ */
+export function buildDocumentIslands(opts) {
+    const searchHref = opts.searchHref || 'document.search.json';
+    /** @type {any[]} */
+    const islands = [
+        {
+            name: 'DocumentSearch',
+            kind: 'search',
+            resume: 'island',
+            index: searchHref,
+        },
+    ];
+    const fences = opts.evidence?.fences || [];
+    for (let i = 0; i < fences.length; i++) {
+        const f = fences[i];
+        const meta = parseFenceInfo(f.info);
+        const interactive = Boolean(meta.playground || meta.run);
+        if (!interactive)
+            continue;
+        if (f.status && f.status !== 'ok' && f.status !== 'highlight')
+            continue;
+        if (meta.lang !== 'vmz' && !meta.playground)
+            continue;
+        const name = `DocumentPlayground:${f.locale}:${f.pageKey}:${f.lineStart || i}`;
+        const bodyKey = `${f.locale}:${f.pageKey}:${f.lineStart}`;
+        islands.push({
+            name,
+            kind: 'playground',
+            resume: 'island',
+            fence: {
+                lang: meta.lang,
+                run: meta.run,
+                playground: Boolean(meta.playground),
+                source: meta.source,
+                pageKey: f.pageKey,
+                locale: f.locale,
+                path: f.path,
+                lineStart: f.lineStart,
+                lineEnd: f.lineEnd,
+                status: f.status,
+            },
+            preview: opts.fenceBodies?.get(bodyKey) ?? null,
+        });
+    }
+    return {
+        schema: DOCUMENT_ISLANDS_SCHEMA,
+        hydrate: 'island-only',
+        fullPageHydrate: false,
+        islands,
+        status: 'ready',
+    };
+}
+/**
+ * Relative href from an HTML page to a root artifact (posix).
+ * @param {string} htmlRel
+ * @param {string} artifactName
+ */
+export function artifactHrefFromHtml(htmlRel, artifactName) {
+    const depth = String(htmlRel).replace(/\\/g, '/').split('/').length - 1;
+    const prefix = depth > 0 ? '../'.repeat(depth) : './';
+    return prefix + artifactName;
+}
+/**
+ * Stable map key for fence body lookup.
+ * @param {{ locale: string, pageKey: string, lineStart: number }} f
+ */
+export function fenceBodyKey(f) {
+    return `${f.locale}:${f.pageKey}:${f.lineStart}`;
+}
+/**
+ * Collect fence bodies from analyzeMarkdown results for playground islands.
+ * @param {Map<string, { fences?: any[] }>} analyzedByPageId locale:pageKey → analyze result
+ * @param {any[]} pages manifest.pages
+ */
+export function collectFenceBodies(analyzedByPageId, pages) {
+    /** @type {Map<string, string>} */
+    const out = new Map();
+    for (const page of pages || []) {
+        const id = `${page.identity.locale}:${page.identity.pageKey}`;
+        const analyzed = analyzedByPageId.get(id);
+        if (!analyzed?.fences)
+            continue;
+        for (const fence of analyzed.fences) {
+            const meta = parseFenceInfo(fence.info);
+            if (!(meta.playground || meta.run) || meta.lang !== 'vmz')
+                continue;
+            out.set(fenceBodyKey({
+                locale: page.identity.locale,
+                pageKey: page.identity.pageKey,
+                lineStart: fence.lineStart,
+            }), String(fence.content || '').trim());
+        }
+    }
+    return out;
+}
+/**
+ * Render SSR island shells (no script — resume later).
+ * @param {{
+ * islands: any,
+ * searchIndexHref: string,
+ * pageKey: string,
+ * locale: string,
+ * }} opts
+ */
+export function renderIslandShellsHtml(opts) {
+    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const search = `
+  <div
+    data-vmz-island="DocumentSearch"
+    data-vmz-resume="island"
+    data-vmz-search-index="${esc(opts.searchIndexHref)}"
+    role="search"
+    aria-label="Document search"
+  >
+    <p class="doc-search-fallback">Search requires Island resume; use navigation without JavaScript.</p>
+  </div>`;
+    const playgrounds = (opts.islands?.islands || [])
+        .filter((isl) => isl.kind === 'playground' && isl.fence?.locale === opts.locale && isl.fence?.pageKey === opts.pageKey)
+        .map((isl) => {
+        const preview = isl.preview ? `<pre class="doc-playground-source"><code>${esc(isl.preview)}</code></pre>` : '';
+        return `
+  <div
+    data-vmz-island="${esc(isl.name)}"
+    data-vmz-resume="island"
+    data-vmz-playground="1"
+    data-vmz-fence-lang="${esc(isl.fence?.lang || 'vmz')}"
+    aria-label="Interactive example"
+  >
+    <p class="doc-playground-fallback">Interactive example resumes as an Island; source remains readable above.</p>
+    ${preview}
+  </div>`;
+    })
+        .join('');
+    return { searchHtml: search, playgroundHtml: playgrounds };
+}

package/dist/document-locale.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Locale key validation & canonicalization .
+ */
+/**
+ * Soft-normalize for alias / conflict detection (does not validate).
+ * @param {string} raw
+ */
+export declare function softNormalizeLocale(raw: any): string;
+/**
+ * Map soft-normalized key through alias table.
+ * @param {string} soft
+ */
+export declare function canonicalLocale(soft: any): any;
+/**
+ * Validate a top-level locale directory name.
+ * @param {string} literal
+ * @returns {{ ok: true, soft: string, canonical: string } | { ok: false, code: string, message: string }}
+ */
+export declare function validateLocaleLiteral(literal: any): {
+    ok: boolean;
+    code: string;
+    message: string;
+    soft?: undefined;
+    canonical?: undefined;
+} | {
+    ok: boolean;
+    soft: string;
+    canonical: any;
+    code?: undefined;
+    message?: undefined;
+};

package/dist/document-locale.js

@@ -0,0 +1,59 @@
+// @ts-nocheck
+/**
+ * Locale key validation & canonicalization .
+ */
+import { LOCALE_ALIASES } from './document-schema.js';
+/** Literal must be lowercase ASCII BCP 47-ish with `-` separators only. */
+const LOCALE_LITERAL_RE = /^[a-z]{2,3}(-[a-z0-9]+)*$/;
+/**
+ * Soft-normalize for alias / conflict detection (does not validate).
+ * @param {string} raw
+ */
+export function softNormalizeLocale(raw) {
+    return String(raw || '')
+        .trim()
+        .toLowerCase()
+        .replace(/_/g, '-');
+}
+/**
+ * Map soft-normalized key through alias table.
+ * @param {string} soft
+ */
+export function canonicalLocale(soft) {
+    const s = softNormalizeLocale(soft);
+    return LOCALE_ALIASES[s] || s;
+}
+/**
+ * Validate a top-level locale directory name.
+ * @param {string} literal
+ * @returns {{ ok: true, soft: string, canonical: string } | { ok: false, code: string, message: string }}
+ */
+export function validateLocaleLiteral(literal) {
+    const name = String(literal || '');
+    if (!name) {
+        return { ok: false, code: 'document::locale::invalid', message: 'empty locale key' };
+    }
+    if (name.includes('_')) {
+        return {
+            ok: false,
+            code: 'document::locale::separator',
+            message: `locale key must use '-' not '_': ${JSON.stringify(name)}`,
+        };
+    }
+    if (name !== name.toLowerCase()) {
+        return {
+            ok: false,
+            code: 'document::locale::case',
+            message: `locale key must be lowercase ASCII (got ${JSON.stringify(name)}; use ${JSON.stringify(name.toLowerCase())})`,
+        };
+    }
+    if (!LOCALE_LITERAL_RE.test(name)) {
+        return {
+            ok: false,
+            code: 'document::locale::invalid',
+            message: `locale key is not a valid lowercase BCP 47 form: ${JSON.stringify(name)}`,
+        };
+    }
+    const soft = softNormalizeLocale(name);
+    return { ok: true, soft, canonical: canonicalLocale(soft) };
+}

package/dist/document-markdown.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Document — resolve engines.markdown via the official plugin runtime.
+ */
+/**
+ * @param {{ engines?: { markdown?: string } }} [opts]
+ */
+export declare function resolveMarkdownEngine(opts?: {}): Promise<{
+    engine: any;
+    analyzeMarkdown: any;
+    renderMarkdown: any;
+    slugify: any;
+}>;

package/dist/document-markdown.js

@@ -0,0 +1,45 @@
+// @ts-nocheck
+/**
+ * Document — resolve engines.markdown via the official plugin runtime.
+ */
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { importMaybeTs } from './plugin-host.js';
+const require = createRequire(import.meta.url);
+/**
+ * @param {{ engines?: { markdown?: string } }} [opts]
+ */
+export async function resolveMarkdownEngine(opts = {}) {
+    const id = opts.engines?.markdown || 'markdown-it';
+    if (id !== 'markdown-it') {
+        throw new Error(`unsupported engines.markdown ${JSON.stringify(id)} (markdown-it only)`);
+    }
+    let runtimeFile = null;
+    try {
+        const pkg = require.resolve('@vmz/plugin-markdown-it/package.json');
+        runtimeFile = path.join(path.dirname(pkg), 'runtime.ts');
+    }
+    catch {
+        // Developer mode: monorepo source checkout.
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const fallback = path.resolve(here, '../../../plugins/vmz-plugin-markdown-it/runtime.ts');
+        if (existsSync(fallback))
+            runtimeFile = fallback;
+    }
+    if (!runtimeFile || !existsSync(runtimeFile)) {
+        throw new Error('markdown engine needs `@vmz/plugin-markdown-it` (optional peer of `@vmz/vmz`).\n' +
+            '  Install:  pnpm add -D @vmz/plugin-markdown-it');
+    }
+    const mod = await importMaybeTs(runtimeFile);
+    if (typeof mod.analyzeMarkdown !== 'function') {
+        throw new Error(`cannot load markdown engine markdown-it from ${runtimeFile}`);
+    }
+    return {
+        engine: id,
+        analyzeMarkdown: mod.analyzeMarkdown,
+        renderMarkdown: mod.renderMarkdown,
+        slugify: mod.slugify,
+    };
+}

package/dist/document-scan.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Scan /documents tree → pages + locale dirs .
+ */
+/**
+ * PageKey from locale-relative markdown path (strip extension; index → parent or "index").
+ * @param {string} relMd e.g. guide/install.md | index.md | guide/index.md
+ */
+export declare function pageKeyFromRel(relMd: any): any;
+/**
+ * @param {string} documentsRoot absolute path to .../documents
+ * @returns {{
+ * locales: string[],
+ * pages: Array<{ identity: { pageKey: string, locale: string }, sourcePath: string }>,
+ * diagnostics: Array<{ code: string, severity: string, message: string, path?: string }>,
+ * }}
+ */
+export declare function scanDocumentsTree(documentsRoot: any): {
+    locales: any[];
+    pages: any[];
+    diagnostics: any[];
+};

package/dist/document-scan.js

@@ -0,0 +1,151 @@
+// @ts-nocheck
+/**
+ * Scan /documents tree → pages + locale dirs .
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DIAG, DOCUMENT_RESERVED_TOP } from './document-schema.js';
+import { canonicalLocale, softNormalizeLocale, validateLocaleLiteral } from './document-locale.js';
+/**
+ * @param {string} dir
+ * @param {(rel: string) => void} visit
+ * @param {string} [prefix]
+ */
+function walkMd(dir, visit, prefix = '') {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of entries) {
+        if (ent.name.startsWith('.'))
+            continue;
+        const rel = prefix ? `${prefix}/${ent.name}` : ent.name;
+        const full = path.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            walkMd(full, visit, rel);
+        }
+        else if (ent.isFile() && /\.md$/i.test(ent.name)) {
+            visit(rel.replace(/\\/g, '/'));
+        }
+    }
+}
+/**
+ * PageKey from locale-relative markdown path (strip extension; index → parent or "index").
+ * @param {string} relMd e.g. guide/install.md | index.md | guide/index.md
+ */
+export function pageKeyFromRel(relMd) {
+    const norm = relMd.replace(/\\/g, '/').replace(/^\.\//, '');
+    let withoutExt = norm.replace(/\.md$/i, '');
+    if (withoutExt.endsWith('/index')) {
+        withoutExt = withoutExt.slice(0, -'/index'.length);
+    }
+    else if (withoutExt === 'index') {
+        withoutExt = 'index';
+    }
+    return withoutExt.replace(/^\/+|\/+$/g, '') || 'index';
+}
+/**
+ * @param {string} documentsRoot absolute path to .../documents
+ * @returns {{
+ * locales: string[],
+ * pages: Array<{ identity: { pageKey: string, locale: string }, sourcePath: string }>,
+ * diagnostics: Array<{ code: string, severity: string, message: string, path?: string }>,
+ * }}
+ */
+export function scanDocumentsTree(documentsRoot) {
+    /** @type {Array<{ code: string, severity: string, message: string, path?: string }>} */
+    const diagnostics = [];
+    /** @type {string[]} */
+    const locales = [];
+    /** @type {Array<{ identity: { pageKey: string, locale: string }, sourcePath: string }>} */
+    const pages = [];
+    if (!fs.existsSync(documentsRoot) || !fs.statSync(documentsRoot).isDirectory()) {
+        diagnostics.push({
+            code: DIAG.LAYOUT_MISSING_DOCUMENTS,
+            severity: 'error',
+            message: `documents root missing: ${documentsRoot}`,
+            path: documentsRoot,
+        });
+        return { locales, pages, diagnostics };
+    }
+    /** @type {Map<string, string[]>} canonical → literals */
+    const byCanonical = new Map();
+    const top = fs.readdirSync(documentsRoot, { withFileTypes: true });
+    for (const ent of top) {
+        if (ent.name.startsWith('.'))
+            continue;
+        const full = path.join(documentsRoot, ent.name);
+        if (DOCUMENT_RESERVED_TOP.has(ent.name))
+            continue;
+        if (ent.isFile()) {
+            diagnostics.push({
+                code: DIAG.LAYOUT_ILLEGAL_TOP,
+                severity: 'error',
+                message: `illegal top-level file under documents/ (only package.json, documents.config.*, public/ reserved): ${ent.name}`,
+                path: full,
+            });
+            continue;
+        }
+        if (!ent.isDirectory())
+            continue;
+        const v = validateLocaleLiteral(ent.name);
+        if (!v.ok) {
+            diagnostics.push({
+                code: v.code,
+                severity: 'error',
+                message: v.message,
+                path: full,
+            });
+            // Still try to detect alias conflicts with soft form
+            const soft = softNormalizeLocale(ent.name);
+            const can = canonicalLocale(soft);
+            const list = byCanonical.get(can) || [];
+            list.push(ent.name);
+            byCanonical.set(can, list);
+            continue;
+        }
+        const list = byCanonical.get(v.canonical) || [];
+        list.push(ent.name);
+        byCanonical.set(v.canonical, list);
+        locales.push(ent.name);
+        const seenKeys = new Set();
+        walkMd(full, (relMd) => {
+            const pageKey = pageKeyFromRel(relMd);
+            const sourcePath = path.join(ent.name, relMd).replace(/\\/g, '/');
+            if (seenKeys.has(pageKey)) {
+                diagnostics.push({
+                    code: DIAG.PAGE_DUPLICATE,
+                    severity: 'error',
+                    message: `duplicate PageKey ${JSON.stringify(pageKey)} under locale ${ent.name}`,
+                    path: sourcePath,
+                });
+                return;
+            }
+            seenKeys.add(pageKey);
+            pages.push({
+                identity: { pageKey, locale: ent.name },
+                sourcePath,
+            });
+        });
+    }
+    for (const [canonical, literals] of byCanonical) {
+        const uniq = [...new Set(literals)];
+        if (uniq.length > 1) {
+            diagnostics.push({
+                code: DIAG.LOCALE_CONFLICT,
+                severity: 'error',
+                message: `locale identity conflict for canonical ${JSON.stringify(canonical)}: directories ${uniq.map((s) => JSON.stringify(s)).join(', ')} must not coexist`,
+                path: documentsRoot,
+            });
+        }
+    }
+    locales.sort();
+    pages.sort((a, b) => {
+        const c = a.identity.locale.localeCompare(b.identity.locale);
+        return c !== 0 ? c : a.identity.pageKey.localeCompare(b.identity.pageKey);
+    });
+    return { locales, pages, diagnostics };
+}