@vmz/vmz 0.1.17 → 0.1.19

package/dist/document-layout-render.d.ts

@@ -2,19 +2,10 @@
  * Integrated DocumentMount — compile host chrome via DocumentLayout + createRenderHost.
  * Replaces the removed regex template lowering in document-host-chrome.ts.
  */
-/** @param {string} distDir */
-export declare function resolveDocumentLayoutChunkId(distDir: any): string;
-/**
- * @param {string} distDir
- */
-export declare function assertIntegratedDistReady(distDir: any): string;
-/**
- * @param {string} html
- */
-export declare function assertCompiledShellHtml(html: any): void;
-/**
- * @param {string} distDir
- * @param {string} localeId
- * @param {string} slotHtml
- */
-export declare function renderCompiledDocumentLayout(distDir: any, localeId: any, slotHtml: any): Promise<any>;
+declare global {
+    var __vmzLocaleIdHint: string | undefined;
+}
+export declare function resolveDocumentLayoutChunkId(distDir: string): string | null;
+export declare function assertIntegratedDistReady(distDir: string): string;
+export declare function assertCompiledShellHtml(html: string): void;
+export declare function renderCompiledDocumentLayout(distDir: string, localeId: string, slotHtml: string): Promise<string>;

package/dist/document-layout-render.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Integrated DocumentMount — compile host chrome via DocumentLayout + createRenderHost.
  * Replaces the removed regex template lowering in document-host-chrome.ts.
@@ -7,7 +6,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRenderHost } from '@vmz/core/render-host';
-/** @param {string} distDir */
 export function resolveDocumentLayoutChunkId(distDir) {
     for (const chunkId of ['layouts/DocumentLayout', 'components/DocumentLayout']) {
         if (fs.existsSync(path.join(distDir, `${chunkId}.client.js`)))
@@ -15,9 +13,6 @@ export function resolveDocumentLayoutChunkId(distDir) {
     }
     return null;
 }
-/**
- * @param {string} distDir
- */
 export function assertIntegratedDistReady(distDir) {
     const dom = path.join(distDir, 'vmz-dom.js');
     if (!fs.existsSync(dom)) {
@@ -29,9 +24,6 @@ export function assertIntegratedDistReady(distDir) {
     }
     return chunkId;
 }
-/**
- * @param {string} html
- */
 export function assertCompiledShellHtml(html) {
     const header = html.match(/<header[^>]*data-vmz-fixture="site-header"[\s\S]*?<\/header>/i)?.[0] ?? '';
     const footer = html.match(/<footer[^>]*data-vmz-fixture="site-footer"[\s\S]*?<\/footer>/i)?.[0] ?? '';
@@ -48,20 +40,11 @@ export function assertCompiledShellHtml(html) {
         throw new Error('document layout SSR missing compiled SiteHeader/SiteFooter fixtures');
     }
 }
-/**
- * @param {string} distDir
- * @param {string} chunkId
- */
 async function loadCtor(distDir, chunkId) {
     const href = pathToFileURL(path.join(distDir, `${chunkId}.client.js`)).href;
     const mod = await import(`${href}?t=${Date.now()}`);
     return mod.default;
 }
-/**
- * @param {string} distDir
- * @param {string} localeId
- * @param {string} slotHtml
- */
 export async function renderCompiledDocumentLayout(distDir, localeId, slotHtml) {
     const chunkId = assertIntegratedDistReady(distDir);
     const prevHint = globalThis.__vmzLocaleIdHint;

package/dist/document-locale.d.ts

@@ -1,31 +1,18 @@
 /**
  * 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;
+export type ValidateLocaleResult = {
+    ok: true;
+    soft: string;
+    canonical: string;
+} | {
+    ok: false;
     code: string;
     message: string;
-    soft?: undefined;
-    canonical?: undefined;
-} | {
-    ok: boolean;
-    soft: string;
-    canonical: any;
-    code?: undefined;
-    message?: undefined;
 };
+/** Soft-normalize for alias / conflict detection (does not validate). */
+export declare function softNormalizeLocale(raw: string): string;
+/** Map soft-normalized key through alias table. */
+export declare function canonicalLocale(soft: string): string;
+/** Validate a top-level locale directory name. */
+export declare function validateLocaleLiteral(literal: string): ValidateLocaleResult;

package/dist/document-locale.js

@@ -1,33 +1,22 @@
-// @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
- */
+/** Soft-normalize for alias / conflict detection (does not validate). */
 export function softNormalizeLocale(raw) {
     return String(raw || '')
         .trim()
         .toLowerCase()
         .replace(/_/g, '-');
 }
-/**
- * Map soft-normalized key through alias table.
- * @param {string} soft
- */
+/** Map soft-normalized key through alias table. */
 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 }}
- */
+/** Validate a top-level locale directory name. */
 export function validateLocaleLiteral(literal) {
     const name = String(literal || '');
     if (!name) {

package/dist/document-markdown.d.ts

@@ -1,11 +1,15 @@
 /**
  * Document — resolve engines.markdown via the official plugin runtime.
  */
-/**
- * @param {{ engines?: { markdown?: string } }} [opts]
- */
-export declare function resolveMarkdownEngine(opts?: {}): Promise<{
-    engine: any;
+export interface ResolveMarkdownEngineOpts {
+    engines?: {
+        markdown?: string;
+    };
+    /** Reserved for engine resolution relative to the project (unused by markdown-it). */
+    projectRoot?: string;
+}
+export declare function resolveMarkdownEngine(opts?: ResolveMarkdownEngineOpts): Promise<{
+    engine: string;
     analyzeMarkdown: any;
     renderMarkdown: any;
     slugify: any;

package/dist/document-markdown.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Document — resolve engines.markdown via the official plugin runtime.
  */
@@ -8,9 +7,6 @@ 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') {

package/dist/document-routing-config.d.ts

@@ -1,17 +1,10 @@
 /**
  * Project locale routing — consume Rust LocalePlan (no author JSON5 in TS).
  */
-/**
- * @param {string} projectRoot
- * @returns {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string } | null}
- */
-export declare function loadLocalesRouting(projectRoot: any): {
-    strategy: any;
-    defaultPrefix: any;
-    defaultLocale: any;
-};
-/**
- * @param {string} routeBase
- * @param {string} pageKey
- */
-export declare function docsRouteNone(routeBase: any, pageKey: any): string;
+export interface LocalesRouting {
+    strategy?: string;
+    defaultPrefix?: string;
+    defaultLocale?: string;
+}
+export declare function loadLocalesRouting(projectRoot: string): LocalesRouting | null;
+export declare function docsRouteNone(routeBase: string, pageKey: string): string;

package/dist/document-routing-config.js

@@ -1,12 +1,7 @@
-// @ts-nocheck
 /**
  * Project locale routing — consume Rust LocalePlan (no author JSON5 in TS).
  */
 import { loadLocalePlan } from './author-input.js';
-/**
- * @param {string} projectRoot
- * @returns {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string } | null}
- */
 export function loadLocalesRouting(projectRoot) {
     const plan = loadLocalePlan(projectRoot);
     if (!plan || plan.diagnostics?.some((d) => d.code === 'vmz::locale::manifest_missing')) {
@@ -19,10 +14,6 @@ export function loadLocalesRouting(projectRoot) {
         defaultLocale: plan.defaultLocale || undefined,
     };
 }
-/**
- * @param {string} routeBase
- * @param {string} pageKey
- */
 export function docsRouteNone(routeBase, pageKey) {
     const base = String(routeBase || '/').replace(/\/$/, '') || '';
     const key = pageKey === 'index' ? '' : pageKey.replace(/\\/g, '/');

package/dist/document-scan.d.ts

@@ -1,21 +1,17 @@
 /**
  * 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[];
-};
+import { type DocumentDiagnostic, type PageIdentity } from './document-schema.js';
+interface ScannedPage {
+    identity: PageIdentity;
+    sourcePath: string;
+}
+export interface ScanDocumentsTreeResult {
+    locales: string[];
+    pages: ScannedPage[];
+    diagnostics: DocumentDiagnostic[];
+}
+/** PageKey from locale-relative markdown path (strip extension; index → parent or "index"). */
+export declare function pageKeyFromRel(relMd: string): string;
+export declare function scanDocumentsTree(documentsRoot: string): ScanDocumentsTreeResult;
+export {};

package/dist/document-scan.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Scan /documents tree → pages + locale dirs .
  */
@@ -6,11 +5,6 @@ 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 {
@@ -32,10 +26,7 @@ function walkMd(dir, visit, prefix = '') {
         }
     }
 }
-/**
- * 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
- */
+/** PageKey from locale-relative markdown path (strip extension; index → parent or "index"). */
 export function pageKeyFromRel(relMd) {
     const norm = relMd.replace(/\\/g, '/').replace(/^\.\//, '');
     let withoutExt = norm.replace(/\.md$/i, '');
@@ -47,20 +38,9 @@ export function pageKeyFromRel(relMd) {
     }
     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({
@@ -71,7 +51,6 @@ export function scanDocumentsTree(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) {
@@ -92,7 +71,7 @@ export function scanDocumentsTree(documentsRoot) {
         if (!ent.isDirectory())
             continue;
         const v = validateLocaleLiteral(ent.name);
-        if (!v.ok) {
+        if (v.ok === false) {
             diagnostics.push({
                 code: v.code,
                 severity: 'error',

package/dist/document-schema.d.ts

@@ -3,40 +3,6 @@
  *
  * Not a Doc IR: this is a filesystem/manifest projection only.
  */
-/** @typedef {{ pageKey: string, locale: string }} PageIdentity */
-/** @typedef {{
- * identity: PageIdentity,
- * sourcePath: string,
- * route?: string | null,
- * anchors?: string[],
- * }} PageRecord */
-/** @typedef {{
- * id: string,
- * sourceRoot: string,
- * pageKeys: string[],
- * }} DocumentCollection */
-/** @typedef {{
- * collectionId: string,
- * routeBase: string,
- * mode: 'integrated' | 'standalone',
- * }} DocumentMount */
-/** @typedef {{
- * code: string,
- * severity: 'error' | 'warning',
- * message: string,
- * path?: string,
- * }} DocumentDiagnostic */
-/** @typedef {{
- * schema: typeof DOCUMENT_MANIFEST_SCHEMA,
- * root: string,
- * defaultLocale: string | null,
- * locales: string[],
- * localeLabels: Record<string, string>,
- * collections: DocumentCollection[],
- * mounts: DocumentMount[],
- * pages: PageRecord[],
- * diagnostics: DocumentDiagnostic[],
- * }} DocumentManifest */
 export declare const DOCUMENT_MANIFEST_SCHEMA = "vmz.document.manifest.v0";
 /** Static page view fragment — not a Doc IR. */
 export declare const DOCUMENT_VIEW_SCHEMA = "vmz.document.view.v0";
@@ -46,16 +12,163 @@ export declare const DOCUMENT_EVIDENCE_SCHEMA = "vmz.document.evidence.v0";
 export declare const DOCUMENT_SEARCH_SCHEMA = "vmz.document.search.v0";
 /** Island-only resume plan for search/playground — not a Doc IR. */
 export declare const DOCUMENT_ISLANDS_SCHEMA = "vmz.document.islands.v0";
+export interface PageIdentity {
+    pageKey: string;
+    locale: string;
+}
+export interface PageRecord {
+    identity: PageIdentity;
+    sourcePath: string;
+    route?: string | null;
+    anchors?: string[];
+    title?: string;
+}
+export interface DocumentCollection {
+    id: string;
+    sourceRoot: string;
+    pageKeys: string[];
+}
+export interface DocumentMount {
+    collectionId: string;
+    routeBase: string;
+    mode: 'integrated' | 'standalone';
+}
+export interface DocumentDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    path?: string;
+}
+export interface DocumentFenceRecord {
+    lang: string;
+    info?: string;
+    lineStart?: number;
+    lineEnd?: number;
+    pageKey: string;
+    locale: string;
+    path?: string;
+    run?: string | null;
+    source?: string | null;
+    playground?: boolean;
+    status?: string;
+    detail?: string;
+}
+export interface DocumentApiMatch {
+    chunkId?: string;
+    name?: string;
+    source?: string;
+    capabilities?: string[];
+    stableId?: {
+        kind: string;
+        id?: string;
+    };
+}
+export interface DocumentApiRef {
+    query: string;
+    pageKey: string;
+    locale: string;
+    path?: string;
+    status: string;
+    matches: DocumentApiMatch[];
+}
+export interface DocumentEvidence {
+    schema: typeof DOCUMENT_EVIDENCE_SCHEMA;
+    fences: DocumentFenceRecord[];
+    apiRefs: DocumentApiRef[];
+    testSelections: unknown[];
+    status: string;
+}
+export interface DocumentSearchHeading {
+    id: string;
+    level: number;
+    text: string;
+}
+export interface DocumentSearchRecord {
+    kind: string;
+    id: string;
+    locale: string;
+    pageKey: string;
+    route?: string | null;
+    title?: string;
+    text?: string;
+    headings?: DocumentSearchHeading[];
+    headingId?: string;
+    headingLevel?: number;
+    apiSymbolIds?: string[];
+    apiSymbolId?: string;
+    stableId?: {
+        kind: string;
+        id?: string;
+    };
+    version?: string | null;
+}
+export interface DocumentSearchIndex {
+    schema: typeof DOCUMENT_SEARCH_SCHEMA;
+    status: string;
+    version: string | null;
+    records: DocumentSearchRecord[];
+}
+export interface DocumentIslandFence {
+    lang?: string;
+    run?: string | null;
+    playground?: boolean;
+    source?: string | null;
+    pageKey: string;
+    locale: string;
+    path?: string;
+    lineStart?: number;
+    lineEnd?: number;
+    status?: string;
+}
+export interface DocumentIsland {
+    name: string;
+    kind: string;
+    resume: string;
+    index?: string | null;
+    fence?: DocumentIslandFence;
+    preview?: string | null;
+}
+export interface DocumentIslandsPlan {
+    schema: typeof DOCUMENT_ISLANDS_SCHEMA;
+    hydrate: string;
+    fullPageHydrate: boolean;
+    islands: DocumentIsland[];
+    status: string;
+}
+export interface DocumentBuildMeta {
+    engine?: string;
+    outDir?: string;
+    designs?: string | null;
+    designsCss?: string | null;
+    hostShell?: string;
+    pages?: Array<{
+        route: string;
+        htmlPath: string;
+        viewPath: string;
+    }>;
+    evidence?: string;
+    search?: string;
+    islands?: string;
+}
+export interface DocumentManifest {
+    schema: typeof DOCUMENT_MANIFEST_SCHEMA;
+    root: string;
+    defaultLocale: string | null;
+    locales: string[];
+    localeLabels: Record<string, string>;
+    collections: DocumentCollection[];
+    mounts: DocumentMount[];
+    pages: PageRecord[];
+    diagnostics: DocumentDiagnostic[];
+    evidence?: DocumentEvidence;
+    search?: DocumentSearchIndex;
+    islands?: DocumentIslandsPlan;
+    build?: DocumentBuildMeta;
+}
 /** Top-level non-locale reserved names under /documents */
 export declare const DOCUMENT_RESERVED_TOP: Set<string>;
 /** Known locale aliases → canonical key (lowercase, hyphen). */
-export declare const LOCALE_ALIASES: {
-    'zh-cn': string;
-    'zh-sg': string;
-    'zh-tw': string;
-    'zh-hk': string;
-    'zh-mo': string;
-};
+export declare const LOCALE_ALIASES: Record<string, string>;
 export declare const DIAG: {
     LOCALE_INVALID: string;
     LOCALE_CASE: string;

package/dist/document-schema.js

@@ -1,43 +1,8 @@
-// @ts-nocheck
 /**
  * Document contract — schema constants & diagnostic codes.
  *
  * Not a Doc IR: this is a filesystem/manifest projection only.
  */
-/** @typedef {{ pageKey: string, locale: string }} PageIdentity */
-/** @typedef {{
- * identity: PageIdentity,
- * sourcePath: string,
- * route?: string | null,
- * anchors?: string[],
- * }} PageRecord */
-/** @typedef {{
- * id: string,
- * sourceRoot: string,
- * pageKeys: string[],
- * }} DocumentCollection */
-/** @typedef {{
- * collectionId: string,
- * routeBase: string,
- * mode: 'integrated' | 'standalone',
- * }} DocumentMount */
-/** @typedef {{
- * code: string,
- * severity: 'error' | 'warning',
- * message: string,
- * path?: string,
- * }} DocumentDiagnostic */
-/** @typedef {{
- * schema: typeof DOCUMENT_MANIFEST_SCHEMA,
- * root: string,
- * defaultLocale: string | null,
- * locales: string[],
- * localeLabels: Record<string, string>,
- * collections: DocumentCollection[],
- * mounts: DocumentMount[],
- * pages: PageRecord[],
- * diagnostics: DocumentDiagnostic[],
- * }} DocumentManifest */
 export const DOCUMENT_MANIFEST_SCHEMA = 'vmz.document.manifest.v0';
 /** Static page view fragment — not a Doc IR. */
 export const DOCUMENT_VIEW_SCHEMA = 'vmz.document.view.v0';

package/dist/embedded-packaging.d.ts

@@ -3,20 +3,32 @@
  * Packaging only — does not invent route / MIME / fallback semantics.
  */
 export declare const EMBEDDED_RESOURCE_INDEX_SCHEMA = "vmz.embedded.resource_index.v0";
+interface EmbeddedPackagingOpts {
+    siteId?: string;
+    contractDigest?: string | null;
+}
+interface EmbeddedResourceIndex {
+    schema: string;
+    siteId: string | null;
+    contractDigest: string | null;
+    objectCount: number;
+    objects: Array<{
+        path: string;
+        digest: string;
+        blob: string;
+        bytes: number;
+    }>;
+    indexDigest?: string;
+}
 /**
  * Walk outDir and build path → digest → relative blob path map.
  * Copies files into `dist/_vmz/embedded-baseline/` (whole release, no file-level mix).
  * @param {string} outDir
  * @param {{ siteId?: string, contractDigest?: string | null }} [opts]
  */
-export declare function emitEmbeddedPackaging(outDir: any, opts?: {}): {
-    index: {
-        schema: string;
-        siteId: any;
-        contractDigest: any;
-        objectCount: number;
-        objects: any[];
-    };
+export declare function emitEmbeddedPackaging(outDir: string, opts?: EmbeddedPackagingOpts): {
+    index: EmbeddedResourceIndex;
     indexPath: string;
     baselineDir: string;
 };
+export {};

package/dist/embedded-packaging.js

@@ -2,7 +2,6 @@
  * rust-embedded packaging adapter: resource index + baseline closure.
  * Packaging only — does not invent route / MIME / fallback semantics.
  */
-// @ts-nocheck
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';

package/dist/explain-cmd.d.ts

@@ -1,5 +1,6 @@
 /**
- * @param {string[]} argv
- * @returns {number}
+ * `vmz explain` — DX causal explain; registered on `@vmz/commander`.
  */
-export declare function cmdExplain(argv: any): 0 | 1;
+import type { Cli, ParsedOptions } from '@vmz/commander';
+export declare function registerExplainCommand(cli: Cli): void;
+export declare function cmdExplain(args: ParsedOptions): number;