@vmz/vmz 0.0.2 → 0.0.3

package/dist/document-interactive.js

@@ -1,7 +1,6 @@
 // @ts-nocheck
 /**
- * Document D3 Interactive — search index + Island-only resume plan.
- * Design: 规划设计/vmz/19 §5–6 · §8 D3
+ * 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.
@@ -27,10 +26,10 @@ export function htmlToSearchText(html) {
 }
 /**
  * @param {{
- *   manifest: any,
- *   enriched: { byId: Map<string, any> },
- *   evidence: any,
- *   version?: string | null,
+ * manifest: any,
+ * enriched: { byId: Map<string, any> },
+ * evidence: any,
+ * version?: string | null,
  * }} opts
  */
 export function buildDocumentSearch(opts) {
@@ -114,9 +113,9 @@ export function buildDocumentSearch(opts) {
 /**
  * Island-only resume plan for document surfaces.
  * @param {{
- *   evidence: any,
- *   searchHref?: string,
- *   fenceBodies?: Map<string, string>,
+ * evidence: any,
+ * searchHref?: string,
+ * fenceBodies?: Map<string, string>,
  * }} opts
  */
 export function buildDocumentIslands(opts) {
@@ -216,10 +215,10 @@ export function collectFenceBodies(analyzedByPageId, pages) {
 /**
  * Render SSR island shells (no script — resume later).
  * @param {{
- *   islands: any,
- *   searchIndexHref: string,
- *   pageKey: string,
- *   locale: string,
+ * islands: any,
+ * searchIndexHref: string,
+ * pageKey: string,
+ * locale: string,
  * }} opts
  */
 export function renderIslandShellsHtml(opts) {

package/dist/document-locale.d.ts

@@ -1,5 +1,5 @@
 /**
- * Locale key validation & canonicalization (D0).
+ * Locale key validation & canonicalization .
  */
 /**
  * Soft-normalize for alias / conflict detection (does not validate).

package/dist/document-locale.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 /**
- * Locale key validation & canonicalization (D0).
+ * Locale key validation & canonicalization .
  */
 import { LOCALE_ALIASES } from './document-schema.js';
 /** Literal must be lowercase ASCII BCP 47-ish with `-` separators only. */

package/dist/document-markdown.d.ts

@@ -1,6 +1,5 @@
 /**
- * Document D1 — resolve engines.markdown via the official plugin runtime.
- * Design: 规划设计/vmz/19 §3 · 23 §0（runtime.ts；与 plugin-host 同一 importMaybeTs）.
+ * Document — resolve engines.markdown via the official plugin runtime.
  */
 /**
  * @param {{ engines?: { markdown?: string } }} [opts]

package/dist/document-markdown.js

@@ -1,9 +1,9 @@
 // @ts-nocheck
 /**
- * Document D1 — resolve engines.markdown via the official plugin runtime.
- * Design: 规划设计/vmz/19 §3 · 23 §0（runtime.ts；与 plugin-host 同一 importMaybeTs）.
+ * 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';
@@ -14,17 +14,23 @@ const require = createRequire(import.meta.url);
 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)} (D1: markdown-it only)`);
+        throw new Error(`unsupported engines.markdown ${JSON.stringify(id)} (markdown-it only)`);
     }
-    let runtimeFile;
+    let runtimeFile = null;
     try {
         const pkg = require.resolve('@vmz/plugin-markdown-it/package.json');
         runtimeFile = path.join(path.dirname(pkg), 'runtime.ts');
     }
-    catch (e) {
-        // Workspace fallback when package exports omit package.json.
+    catch {
+        // Developer mode: monorepo source checkout.
         const here = path.dirname(fileURLToPath(import.meta.url));
-        runtimeFile = path.resolve(here, '../../../plugins/vmz-plugin-markdown-it/runtime.ts');
+        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') {

package/dist/document-scan.d.ts

@@ -1,5 +1,5 @@
 /**
- * Scan /documents tree → pages + locale dirs (D0).
+ * Scan /documents tree → pages + locale dirs .
  */
 /**
  * PageKey from locale-relative markdown path (strip extension; index → parent or "index").
@@ -9,9 +9,9 @@ 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 }>,
+ * 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): {

package/dist/document-scan.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 /**
- * Scan /documents tree → pages + locale dirs (D0).
+ * Scan /documents tree → pages + locale dirs .
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -50,9 +50,9 @@ export function pageKeyFromRel(relMd) {
 /**
  * @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 }>,
+ * 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) {

package/dist/document-schema.d.ts

@@ -1,51 +1,50 @@
 /**
- * Document D0 Contract — schema constants & diagnostic codes.
- * Design: 规划设计/vmz/19 §2.3 · D0
+ * 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[],
+ * identity: PageIdentity,
+ * sourcePath: string,
+ * route?: string | null,
+ * anchors?: string[],
  * }} PageRecord */
 /** @typedef {{
- *   id: string,
- *   sourceRoot: string,
- *   pageKeys: string[],
+ * id: string,
+ * sourceRoot: string,
+ * pageKeys: string[],
  * }} DocumentCollection */
 /** @typedef {{
- *   collectionId: string,
- *   routeBase: string,
- *   mode: 'integrated' | 'standalone',
+ * collectionId: string,
+ * routeBase: string,
+ * mode: 'integrated' | 'standalone',
  * }} DocumentMount */
 /** @typedef {{
- *   code: string,
- *   severity: 'error' | 'warning',
- *   message: string,
- *   path?: string,
+ * 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[],
+ * 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 (D1) — not a Doc IR. */
+/** Static page view fragment — not a Doc IR. */
 export declare const DOCUMENT_VIEW_SCHEMA = "vmz.document.view.v0";
-/** D2 evidence projection (fences + API refs) — not a Doc IR. */
+/** Evidence projection (fences + API refs) — not a Doc IR. */
 export declare const DOCUMENT_EVIDENCE_SCHEMA = "vmz.document.evidence.v0";
-/** D3 search index (SearchRecord[]) — not a Doc IR. */
+/** Search index (SearchRecord[]) — not a Doc IR. */
 export declare const DOCUMENT_SEARCH_SCHEMA = "vmz.document.search.v0";
-/** D3 island-only resume plan for search/playground — not a Doc IR. */
+/** Island-only resume plan for search/playground — not a Doc IR. */
 export declare const DOCUMENT_ISLANDS_SCHEMA = "vmz.document.islands.v0";
 /** Top-level non-locale reserved names under /documents */
 export declare const DOCUMENT_RESERVED_TOP: Set<string>;

package/dist/document-schema.js

@@ -1,52 +1,51 @@
 // @ts-nocheck
 /**
- * Document D0 Contract — schema constants & diagnostic codes.
- * Design: 规划设计/vmz/19 §2.3 · D0
+ * 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[],
+ * identity: PageIdentity,
+ * sourcePath: string,
+ * route?: string | null,
+ * anchors?: string[],
  * }} PageRecord */
 /** @typedef {{
- *   id: string,
- *   sourceRoot: string,
- *   pageKeys: string[],
+ * id: string,
+ * sourceRoot: string,
+ * pageKeys: string[],
  * }} DocumentCollection */
 /** @typedef {{
- *   collectionId: string,
- *   routeBase: string,
- *   mode: 'integrated' | 'standalone',
+ * collectionId: string,
+ * routeBase: string,
+ * mode: 'integrated' | 'standalone',
  * }} DocumentMount */
 /** @typedef {{
- *   code: string,
- *   severity: 'error' | 'warning',
- *   message: string,
- *   path?: string,
+ * 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[],
+ * 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 (D1) — not a Doc IR. */
+/** Static page view fragment — not a Doc IR. */
 export const DOCUMENT_VIEW_SCHEMA = 'vmz.document.view.v0';
-/** D2 evidence projection (fences + API refs) — not a Doc IR. */
+/** Evidence projection (fences + API refs) — not a Doc IR. */
 export const DOCUMENT_EVIDENCE_SCHEMA = 'vmz.document.evidence.v0';
-/** D3 search index (SearchRecord[]) — not a Doc IR. */
+/** Search index (SearchRecord[]) — not a Doc IR. */
 export const DOCUMENT_SEARCH_SCHEMA = 'vmz.document.search.v0';
-/** D3 island-only resume plan for search/playground — not a Doc IR. */
+/** Island-only resume plan for search/playground — not a Doc IR. */
 export const DOCUMENT_ISLANDS_SCHEMA = 'vmz.document.islands.v0';
 /** Top-level non-locale reserved names under /documents */
 export const DOCUMENT_RESERVED_TOP = new Set(['package.json', 'documents.config.ts', 'documents.config.json', 'documents.config.js', 'public']);

package/dist/explain-cmd.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 /**
- * `vmz explain` — DX causal explain queries (doc 21).
+ * `vmz explain` — DX causal explain queries .
  *
  * @param {string[]} argv args after `explain`
  */
@@ -69,10 +69,10 @@ export function cmdExplain(argv) {
     for (const e of chain) {
         const from = e.from ? `${e.from.kind}:${e.from.id}` : '?';
         const to = e.to ? `${e.to.kind}:${e.to.id}` : '?';
-        console.log(`  ${from} -> ${to}  (${e.reason})`);
+        console.log(` ${from} -> ${to} (${e.reason})`);
     }
     if (chain.length === 0) {
-        console.log('  (empty chain)');
+        console.log(' (empty chain)');
     }
     return 0;
 }