@vmz/core 0.3.12 → 0.3.14

package/dist/host/serve/hmr-dev.js

@@ -7,10 +7,12 @@ import { listClientComponents } from '../list-client-components.js';
 import { LOCALE_LINK_PLAN_SCHEMA, linkRouteAliasesFromUnits } from '../localize-body-links.js';
 import { loadNativeAddon } from '../native-addon.js';
 import { createRenderHost } from '../render/render-host.js';
+import { resolveRouteLayoutChain } from '../render/route-layout-chain.js';
 import { setRoutes } from '../../faces/vmz-runtime.js';
 import { LOCALE_LINK_PLAN_REL } from './constants.js';
 import { loadDeploymentStyle } from './locale-theme.js';
 import { bustUrl, isEventOnlyShell, isEventStrategy, listPageClientFiles, loadPageResumeEntries, pageNeedsReload } from './page-catalog.js';
+import { packIslandHrefs } from './pack-entry.js';
 import { serveState } from './state.js';
 export function installDevImportTokenHooks() {
     if (!serveState.isDev)
@@ -132,34 +134,52 @@ export async function* emitDevErrorHtml(err) {
 function escapeHtml(s) {
     return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
-function emitEntryClient(eager, lazy, token) {
-    const q = `?t=${token}`;
+/**
+ * 客户端入口模块由 pack 消费，必须保持内容稳定：每次重建都把 `?t=` 注入
+ * 动态 import 会让打包产物每轮都变，也会让浏览器拿到两个不同 URL 的同一模块。
+ * 缓存破坏由打包文件名（内容哈希）与 SSE 侧的 reload 负责。
+ */
+function emitEntryClient(eager, lazy) {
     const native = loadNativeAddon();
     if (typeof native.generateServeEntryClient !== 'function') {
         throw new Error('vmz native addon missing generateServeEntryClient — rebuild with `pnpm napi:build`');
     }
-    return native.generateServeEntryClient(eager, lazy, q);
+    return native.generateServeEntryClient(eager, lazy, '');
 }
-function emitEntryEvent(token) {
-    const q = `?t=${token}`;
+function emitEntryEvent(eager, lazy) {
     const native = loadNativeAddon();
     if (typeof native.generateServeEntryEvent !== 'function') {
         throw new Error('vmz native addon missing generateServeEntryEvent — rebuild with `pnpm napi:build`');
     }
-    return native.generateServeEntryEvent(q);
+    return native.generateServeEntryEvent(eager, lazy, '');
 }
-export async function softReload(opts = {}) {
+let pendingReload = null;
+let pendingRollback = null;
+/**
+ * 第一阶段：加载构建产物、写客户端入口模块，但**不**发布 SSE、不置 ready。
+ *
+ * dev 的浏览器交付必须经 `vmz-pack`，而 pack 由 CLI 侧执行（runtime 不反向
+ * 依赖 `@vmz/vmz`）。因此先把入口写到 outDir，让调用方 pack，再 `commitReload`。
+ */
+export async function prepareReload(opts = {}) {
     const prevToken = serveState.reloadToken;
     const prevCatalog = serveState.pageCatalog;
     const prevCtors = new Map(serveState.pageCtors);
     const nextToken = Date.now();
     serveState.reloadToken = nextToken;
+    pendingReload = null;
+    pendingRollback = () => {
+        serveState.reloadToken = prevToken;
+        serveState.pageCatalog = prevCatalog;
+        serveState.pageCtors.clear();
+        for (const [k, v] of prevCtors)
+            serveState.pageCtors.set(k, v);
+    };
     const affected = opts.payload?.affectedChunks ?? [];
     const seeds = opts.payload?.seedChunks ?? [];
     const full = opts.payload?.full;
     const islandHmr = Boolean(opts.payload?.islandHmr);
     const rerunLoaders = opts.payload?.rerunLoaders ?? [];
-    const skipEntryRewrite = Boolean(opts.payload?.skipEntryRewrite);
     const buildId = opts.payload?.buildId != null ? String(opts.payload.buildId) : null;
     const sourceRevision = opts.payload?.sourceRevision != null ? String(opts.payload.sourceRevision) : null;
     const bundleRevision = opts.payload?.bundleRevision != null ? String(opts.payload.bundleRevision) : null;
@@ -237,13 +257,45 @@ export async function softReload(opts = {}) {
             .map((e) => e.component)
             .filter(Boolean);
         const lazySet = new Set(lazyEventNames);
-        await writeFile(path.join(serveState.distDir, 'entry-client.js'), emitEntryClient(componentEntries.filter((e) => !lazySet.has(e.name)), componentEntries.filter((e) => lazySet.has(e.name)), skipEntryRewrite ? serveState.reloadToken : nextToken), 'utf8');
+        const eagerComponents = componentEntries.filter((e) => !lazySet.has(e.name));
+        const lazyComponents = componentEntries.filter((e) => lazySet.has(e.name));
+        // Bootstrap tables are literal maps keyed by chunkId / island name:
+        // page/layout units must be enumerated (name = chunkId, entry =
+        // `<chunkId>.client.js`), unknown names throw at runtime by design.
+        const pageEntries = serveState.pageCatalog.map((p) => ({ name: p.chunkId, entry: `${p.chunkId}.client.js` }));
+        const layoutNames = new Set();
+        for (const p of serveState.pageCatalog) {
+            try {
+                for (const id of resolveRouteLayoutChain(serveState.distDir, p.chunkId))
+                    layoutNames.add(String(id));
+            }
+            catch {
+                /* page unit without layoutChain in a partial dev build */
+            }
+        }
+        const layoutEntries = [...layoutNames].sort().map((id) => ({ name: id, entry: `${id}.client.js` }));
+        await writeFile(path.join(serveState.distDir, 'entry-client.js'), emitEntryClient([...eagerComponents, ...pageEntries, ...layoutEntries], lazyComponents), 'utf8');
         const strategies = resumeEntries.map((e) => e.strategy);
         const eventOnlyShell = isEventOnlyShell(strategies);
-        await writeFile(path.join(serveState.distDir, 'entry-event.js'), emitEntryEvent(skipEntryRewrite ? serveState.reloadToken : nextToken), 'utf8');
-        serveState.lastDevError = null;
+        await writeFile(path.join(serveState.distDir, 'entry-event.js'), emitEntryEvent([], lazyComponents), 'utf8');
         const mode = islandHmr ? 'island' : eventOnlyShell ? 'event-shell' : 'full';
-        notifySse(JSON.stringify({
+        const info = {
+            affectedChunks: affected,
+            seedChunks: seeds,
+            full: Boolean(full),
+            islandHmr,
+            mode,
+            eventOnlyShell,
+            pageCount: serveState.pageCatalog.length,
+            reloadedPages: islandHmr ? 0 : nextCtors.size,
+            reloadAllPages,
+            buildId: buildId || serveState.lastDevBuildId,
+            sourceRevision,
+            bundleRevision,
+            serveRevision: String(serveState.reloadToken),
+            token: serveState.reloadToken,
+        };
+        const sse = {
             type: 'hmr',
             mode,
             affectedChunks: affected,
@@ -255,7 +307,8 @@ export async function softReload(opts = {}) {
             serveRevision: String(serveState.reloadToken),
             full: Boolean(full),
             eventOnlyShell,
-        }));
+        };
+        let logLine = null;
         if (!opts.quiet) {
             const aff = affected.length > 0 ? ` affected=[${affected.join(', ')}]` : full === false ? ' affected=[]' : '';
             const scope = islandHmr ? 'island' : reloadAllPages ? 'all-pages' : `pages=${nextCtors.size}`;
@@ -263,32 +316,58 @@ export async function softReload(opts = {}) {
             const rev = bid || sourceRevision || bundleRevision
                 ? ` buildId=${bid || '-'} source=${sourceRevision || '-'} bundle=${bundleRevision || '-'} serve=${serveState.reloadToken}`
                 : ` t=${serveState.reloadToken}`;
-            console.log(`vmz serve: soft reload ok (mode=${mode}; ${scope}; catalog=${serveState.pageCatalog.length};${rev}${aff})`);
+            logLine = `vmz serve: soft reload ok (mode=${mode}; ${scope}; catalog=${serveState.pageCatalog.length};${rev}${aff})`;
         }
-        return {
-            affectedChunks: affected,
-            seedChunks: seeds,
-            full: Boolean(full),
-            islandHmr,
-            mode,
-            eventOnlyShell,
-            pageCount: serveState.pageCatalog.length,
-            reloadedPages: islandHmr ? 0 : nextCtors.size,
-            reloadAllPages,
-            buildId: buildId || serveState.lastDevBuildId,
-            sourceRevision,
-            bundleRevision,
-            serveRevision: String(serveState.reloadToken),
-            token: serveState.reloadToken,
-        };
+        pendingReload = { info, sse, logLine };
+        return info;
     }
     catch (err) {
-        serveState.reloadToken = prevToken;
-        serveState.pageCatalog = prevCatalog;
-        serveState.pageCtors.clear();
-        for (const [k, v] of prevCtors)
-            serveState.pageCtors.set(k, v);
+        pendingRollback?.();
+        pendingRollback = null;
+        pendingReload = null;
         serveState.lastDevError = normalizeDevError(err);
         throw err;
     }
 }
+/**
+ * 第二阶段：发布 SSE 并置 ready。island 热更新的地址表从 pack manifest 精确
+ * 查得（逻辑 `chunkId` → chunk 文件、含 `dom.browser` 的共享 chunk），不做后缀
+ * 猜测；查不到即整页 reload。
+ */
+export function commitReload() {
+    const prepared = pendingReload;
+    if (!prepared)
+        throw new Error('commitReload: no prepared reload');
+    let island = null;
+    if (serveState.isDev) {
+        try {
+            island = packIslandHrefs(serveState.distDir);
+        }
+        catch (err) {
+            abortReload(err);
+            throw err;
+        }
+    }
+    pendingReload = null;
+    pendingRollback = null;
+    serveState.lastDevError = null;
+    serveState.ready = true;
+    notifySse(JSON.stringify({ ...prepared.sse, island }));
+    if (prepared.logLine)
+        console.log(prepared.logLine);
+    return { ...prepared.info, island };
+}
+/** pack 失败：回滚到上一轮已发布状态，并以 SSE error 显式告知浏览器。 */
+export function abortReload(err) {
+    pendingReload = null;
+    pendingRollback?.();
+    pendingRollback = null;
+    serveState.ready = false;
+    serveState.lastDevError = normalizeDevError(err);
+    notifySse(JSON.stringify({
+        type: 'error',
+        message: serveState.lastDevError.message,
+        stack: serveState.lastDevError.stack,
+        at: serveState.lastDevError.at,
+    }));
+}

package/dist/host/serve/http.js

@@ -1,7 +1,7 @@
 import http from 'node:http';
 import { handleNodeRequest } from '../../faces/vmz-runtime.js';
 import { SHUTDOWN_TIMEOUT_MS } from './constants.js';
-import { normalizeDevError, notifySse, softReload } from './hmr-dev.js';
+import { abortReload, commitReload, normalizeDevError, notifySse, prepareReload } from './hmr-dev.js';
 import { renderPage, renderPageStream } from './page-render.js';
 import { serveState } from './state.js';
 function readRequestBody(req) {
@@ -70,21 +70,38 @@ export function startServeHttp() {
         if (url.pathname === '/__vmz/reload' && req.method === 'POST') {
             readRequestBody(req)
                 .then((raw) => {
-                let payload = {};
+                let body = {};
                 try {
-                    payload = raw ? JSON.parse(String(raw)) : {};
+                    body = raw ? JSON.parse(String(raw)) : {};
                 }
                 catch {
-                    payload = {};
+                    body = {};
                 }
-                return softReload({ payload });
+                // dev 两阶段：prepare 写入口 → CLI 侧 `vmz-pack` → commit 发布。
+                // 未带 phase 的请求不属于 v0 合同，直接拒绝而不是猜测阶段。
+                const phase = body.phase;
+                if (phase === 'prepare') {
+                    return prepareReload({ payload: body.payload }).then((info) => ({
+                        phase,
+                        info,
+                    }));
+                }
+                if (phase === 'commit') {
+                    return { phase, info: commitReload() };
+                }
+                if (phase === 'abort') {
+                    const rawError = body.error;
+                    abortReload(new Error(rawError?.message || 'pack failed'));
+                    return { phase, info: { ok: true } };
+                }
+                throw Object.assign(new Error('reload: unknown phase'), { statusCode: 400 });
             })
-                .then((info) => {
+                .then(({ phase, info }) => {
                 res.writeHead(200, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({ ok: true, token: serveState.reloadToken, ...info }));
+                res.end(JSON.stringify({ ok: true, phase, ...info }));
             })
                 .catch((err) => {
-                console.error('vmz serve: soft reload failed', err);
+                console.error('vmz serve: reload failed', err);
                 serveState.lastDevError = normalizeDevError(err);
                 notifySse(JSON.stringify({
                     type: 'error',

package/dist/host/serve/pack-entry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Resolve the browser URL of a packed bootstrap entry from
+ * `_vmz/pack-manifest.json`.
+ *
+ * The manifest is the only logical → physical map for browser delivery. A
+ * missing manifest or a missing logical name is an explicit error: serving the
+ * unpacked root module would hand the browser bare package specifiers that only
+ * `vmz-pack` rewrites.
+ */
+export declare function packEntryHref(distDir: string, logical: string): string;
+/**
+ * 部署单元逻辑 `chunkId` → 浏览器 chunk URL。
+ *
+ * 只读 `unitChunks[]` 的精确 `logical` 匹配：逻辑 `chunkId` 与 pack chunk id
+ * 不保证相同，禁止前缀推导或后缀猜测。单元未进客户端图（`fileName: null`）
+ * 视为错误，消费方不得回退到未打包文件。
+ */
+export declare function packChunkHref(distDir: string, logical: string): string;
+/** 含指定产物模块的 chunk URL（精确路径匹配，如 `dom.browser.js`）。 */
+export declare function packModuleChunkHref(distDir: string, moduleRel: string): string;
+export interface PackIslandHrefs {
+    /** 含 `dom.browser` 的共享 chunk（`hydrate` 由该 chunk 导出）。 */
+    dom: string;
+    /** 部署单元逻辑 `chunkId` → 其客户端 chunk URL（未进图的不列出）。 */
+    pages: Record<string, string>;
+}
+/**
+ * island 热更新地址表：一次读 manifest，给出 runtime 共享 chunk 与各页面 chunk
+ * 的 URL。调用方只按 `data-vmz-page` 逻辑名查表，缺失即走整页 reload。
+ */
+export declare function packIslandHrefs(distDir: string): PackIslandHrefs;

package/dist/host/serve/pack-entry.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const PACK_MANIFEST_REL = ['_vmz', 'pack-manifest.json'];
+const PACK_OUTPUT_DIR_REL = ['_vmz', 'pack'];
+const DEFAULT_PUBLIC_BASE = '/';
+function readPackManifest(distDir, caller) {
+    const manifestPath = path.join(distDir, ...PACK_MANIFEST_REL);
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`${caller}: missing pack manifest at ${manifestPath} — run vmz build (pack) first`);
+    }
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+function chunkHref(manifest, fileName) {
+    const base = String(manifest.publicBase || DEFAULT_PUBLIC_BASE).replace(/\/$/, '');
+    return `${base}/${PACK_OUTPUT_DIR_REL.join('/')}/${fileName}`;
+}
+/**
+ * 模块路径比较键：去掉 Windows verbatim 前缀（Rust `canonicalize` 给
+ * `//?/E:/…`，Node 给 `E:/…`）并统一分隔符，避免同一文件因前缀差异查不到。
+ */
+function moduleKey(filePath) {
+    return filePath.replace(/^(?:\\\\\?\\|\/\/\?\/)/, '').replace(/\\/g, '/');
+}
+/**
+ * Resolve the browser URL of a packed bootstrap entry from
+ * `_vmz/pack-manifest.json`.
+ *
+ * The manifest is the only logical → physical map for browser delivery. A
+ * missing manifest or a missing logical name is an explicit error: serving the
+ * unpacked root module would hand the browser bare package specifiers that only
+ * `vmz-pack` rewrites.
+ */
+export function packEntryHref(distDir, logical) {
+    const manifest = readPackManifest(distDir, 'packEntryHref');
+    const hit = (manifest.entryFiles || []).find((entry) => entry && entry.logical === logical);
+    if (!hit || typeof hit.file !== 'string' || !hit.file) {
+        throw new Error(`packEntryHref: pack manifest has no entry file for "${logical}"`);
+    }
+    return chunkHref(manifest, hit.file);
+}
+/**
+ * 部署单元逻辑 `chunkId` → 浏览器 chunk URL。
+ *
+ * 只读 `unitChunks[]` 的精确 `logical` 匹配：逻辑 `chunkId` 与 pack chunk id
+ * 不保证相同，禁止前缀推导或后缀猜测。单元未进客户端图（`fileName: null`）
+ * 视为错误，消费方不得回退到未打包文件。
+ */
+export function packChunkHref(distDir, logical) {
+    const manifest = readPackManifest(distDir, 'packChunkHref');
+    const hit = (manifest.unitChunks || []).find((entry) => entry && entry.logical === logical);
+    if (!hit) {
+        throw new Error(`packChunkHref: pack manifest has no unit chunk for "${logical}"`);
+    }
+    if (typeof hit.fileName !== 'string' || !hit.fileName) {
+        throw new Error(`packChunkHref: unit "${logical}" is not in the browser client graph`);
+    }
+    return chunkHref(manifest, hit.fileName);
+}
+/** 含指定产物模块的 chunk URL（精确路径匹配，如 `dom.browser.js`）。 */
+export function packModuleChunkHref(distDir, moduleRel) {
+    const manifest = readPackManifest(distDir, 'packModuleChunkHref');
+    const target = moduleKey(path.join(distDir, ...moduleRel.split('/')));
+    for (const chunk of manifest.chunks || []) {
+        if (typeof chunk.fileName !== 'string' || !chunk.fileName)
+            continue;
+        for (const module of chunk.modules || []) {
+            if (moduleKey(String(module)) === target)
+                return chunkHref(manifest, chunk.fileName);
+        }
+    }
+    throw new Error(`packModuleChunkHref: no chunk carries "${moduleRel}"`);
+}
+/**
+ * island 热更新地址表：一次读 manifest，给出 runtime 共享 chunk 与各页面 chunk
+ * 的 URL。调用方只按 `data-vmz-page` 逻辑名查表，缺失即走整页 reload。
+ */
+export function packIslandHrefs(distDir) {
+    const manifest = readPackManifest(distDir, 'packIslandHrefs');
+    const pages = {};
+    for (const unit of manifest.unitChunks || []) {
+        if (!unit || typeof unit.logical !== 'string' || !unit.logical)
+            continue;
+        if (typeof unit.fileName !== 'string' || !unit.fileName)
+            continue;
+        pages[unit.logical] = chunkHref(manifest, unit.fileName);
+    }
+    const target = moduleKey(path.join(distDir, 'dom.browser.js'));
+    for (const chunk of manifest.chunks || []) {
+        if (typeof chunk.fileName !== 'string' || !chunk.fileName)
+            continue;
+        for (const module of chunk.modules || []) {
+            if (moduleKey(String(module)) === target) {
+                return { dom: chunkHref(manifest, chunk.fileName), pages };
+            }
+        }
+    }
+    throw new Error('packIslandHrefs: no chunk carries "dom.browser.js"');
+}

package/dist/host/serve/page-render.js

@@ -6,6 +6,7 @@ import { extractRouteParams, findRootCatchAll, isRootCatchAll, matchFileRoute }
 import { emitDevErrorHtml, normalizeDevError } from './hmr-dev.js';
 import { cssEntryWithBust, htmlThemeAttrPair, localeBootstrapScript, pageMetaAlternates, resolveLocalePath, resolveThemeId, siteFaviconHeadHtml, themeBootstrapScript, } from './locale-theme.js';
 import { isEventOnlyShell, loadPageCtor, loadPageResumeEntries, runRouteGate } from './page-catalog.js';
+import { packEntryHref } from './pack-entry.js';
 import { serveState } from './state.js';
 export async function renderPage(pathname, opts = {}) {
     const rendered = await renderPageStream(pathname, opts);
@@ -290,11 +291,15 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
       hideOverlay();
       if (msg.mode === "island") {
         try {
-          const { hydrate } = await import("/dom.browser.js?t=" + msg.token);
+          // 地址表来自 pack manifest（逻辑名精确匹配），缺失即整页 reload：
+          // 不再单独加载裸 dom.browser.js，避免与 packed bootstrap 形成两份 runtime。
+          const island = msg.island || {};
           const root = document.getElementById("app");
           const pageChunk = root && root.getAttribute("data-vmz-page");
-          if (root && pageChunk) {
-            const pageMod = await import("/" + pageChunk + ".client.js?t=" + msg.token);
+          const pageHref = pageChunk && island.pages ? island.pages[pageChunk] : null;
+          if (root && pageChunk && island.dom && pageHref) {
+            const { hydrate } = await import(island.dom);
+            const pageMod = await import(pageHref);
             let hmrProps = {};
             try {
               const raw = root.getAttribute("data-vmz-props");
@@ -393,7 +398,10 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
     if (typeof native.generatePageShell !== 'function') {
         throw new Error('vmz native addon missing generatePageShell — rebuild with `pnpm napi:build`');
     }
-    const entrySrc = `/${eventOnlyShell ? 'entry-event.js' : 'entry-client.js'}?t=${serveState.reloadToken}`;
+    // 客户端入口一律经 pack manifest 解析：原始 `entry-client.js` 及其拉取的
+    // 客户端模块保留裸包说明符，浏览器无法解析。dev 与生产因此走同一张表。
+    const entryLogical = eventOnlyShell ? 'entry-event.js' : 'entry-client.js';
+    const entrySrc = packEntryHref(serveState.distDir, entryLogical);
     const cssHref = cssEntryWithBust(serveState.cssEntry);
     yield native.generatePageShell({
         bodyHtml,

package/dist/shared/dom-attr-normalize.d.ts

@@ -1,8 +1,22 @@
 /**
  * Shared class/style normalization for Direct SSR + client (0.1.33).
  * Vue-compatible: string | string[] | object map | falsy parts.
+ *
+ * Style keys are normalized to CSS property spelling so SSR text and client
+ * patches agree: camelCase becomes kebab-case, custom properties (`--x`) pass
+ * through untouched, and names that cannot be CSS properties (whitespace, `;`,
+ * `:`, leading digit) are dropped — the same fate invalid declarations have in
+ * the browser. Numeric values gain `px` except for unitless properties, `0`,
+ * and custom properties. Array values emit repeated declarations (vendor
+ * fallback chains) and nested arrays flatten.
  */
 /** Normalize one or more class fragments into a deduped class string. */
 export declare function mergeClassParts(...parts: unknown[]): string;
+/**
+ * Split a style fragment on top-level `;`. Semicolons inside `url(...)` /
+ * nested parens and inside quotes (e.g. `content: 'a;b'`, data URIs with
+ * `;base64,`) do not split — a naive split would truncate those values.
+ */
+export declare function splitStyleDeclarations(text: string): string[];
 /** Merge static + dynamic style fragments; later parts override same keys. */
 export declare function mergeStyleParts(...parts: unknown[]): string;

package/dist/shared/dom-attr-normalize.js

@@ -1,6 +1,14 @@
 /**
  * Shared class/style normalization for Direct SSR + client (0.1.33).
  * Vue-compatible: string | string[] | object map | falsy parts.
+ *
+ * Style keys are normalized to CSS property spelling so SSR text and client
+ * patches agree: camelCase becomes kebab-case, custom properties (`--x`) pass
+ * through untouched, and names that cannot be CSS properties (whitespace, `;`,
+ * `:`, leading digit) are dropped — the same fate invalid declarations have in
+ * the browser. Numeric values gain `px` except for unitless properties, `0`,
+ * and custom properties. Array values emit repeated declarations (vendor
+ * fallback chains) and nested arrays flatten.
  */
 function pushClassTokens(out, value) {
     if (value == null || value === false)
@@ -35,37 +43,168 @@ export function mergeClassParts(...parts) {
         pushClassTokens(tokens, part);
     return [...new Set(tokens)].join(' ');
 }
-function parseStyleObject(value) {
-    const out = {};
+/** CSS properties whose numeric values stay unitless (kebab-case names). */
+const UNITLESS_STYLE_PROPS = new Set([
+    'animation-iteration-count',
+    'aspect-ratio',
+    'border-image-outset',
+    'border-image-slice',
+    'border-image-width',
+    'box-flex',
+    'box-flex-group',
+    'box-ordinal-group',
+    'column-count',
+    'columns',
+    'flex',
+    'flex-grow',
+    'flex-positive',
+    'flex-shrink',
+    'flex-negative',
+    'flex-order',
+    'grid-row',
+    'grid-row-end',
+    'grid-row-span',
+    'grid-row-start',
+    'grid-column',
+    'grid-column-end',
+    'grid-column-span',
+    'grid-column-start',
+    'font-weight',
+    'line-clamp',
+    'line-height',
+    'opacity',
+    'order',
+    'orphans',
+    'scale',
+    'tab-size',
+    'widows',
+    'z-index',
+    'zoom',
+    'fill-opacity',
+    'flood-opacity',
+    'stop-opacity',
+    'stroke-dasharray',
+    'stroke-dashoffset',
+    'stroke-miterlimit',
+    'stroke-opacity',
+    'stroke-width',
+]);
+/** camelCase → kebab-case, `--custom` preserved; `null` when not a CSS property name. */
+function normalizeStyleKey(raw) {
+    const key = raw.trim();
+    if (!key)
+        return null;
+    if (key.startsWith('--')) {
+        return /^--[\w-]+$/.test(key) ? key : null;
+    }
+    const kebab = key.replace(/\B([A-Z])/g, '-$1').toLowerCase();
+    return /^[a-z][a-z0-9-]*$/.test(kebab) ? kebab : null;
+}
+/** One style value as declaration text; `null` drops the declaration. */
+function normalizeStyleValue(key, value) {
+    if (value == null || value === false)
+        return null;
+    if (typeof value === 'number' && value !== 0 && !key.startsWith('--') && !isUnitlessStyleProp(key)) {
+        return `${value}px`;
+    }
+    return String(value);
+}
+/** Unitless lookup ignores vendor prefixes (`webkit-line-clamp` ≙ `line-clamp`). */
+function isUnitlessStyleProp(key) {
+    const unprefixed = key.replace(/^(?:-?(?:webkit|moz|ms|o))-/, '');
+    return UNITLESS_STYLE_PROPS.has(unprefixed);
+}
+function pushStyleValues(out, key, value) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            pushStyleValues(out, key, item);
+        return;
+    }
+    const text = normalizeStyleValue(key, value);
+    if (text != null)
+        out.push(text);
+}
+/**
+ * Split a style fragment on top-level `;`. Semicolons inside `url(...)` /
+ * nested parens and inside quotes (e.g. `content: 'a;b'`, data URIs with
+ * `;base64,`) do not split — a naive split would truncate those values.
+ */
+export function splitStyleDeclarations(text) {
+    const chunks = [];
+    let depth = 0;
+    let quote = null;
+    let start = 0;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (quote != null) {
+            if (ch === '\\') {
+                i += 2;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === '(') {
+            depth += 1;
+        }
+        else if (ch === ')') {
+            if (depth > 0)
+                depth -= 1;
+        }
+        else if (ch === ';' && depth === 0) {
+            chunks.push(text.slice(start, i));
+            start = i + 1;
+        }
+        i += 1;
+    }
+    chunks.push(text.slice(start));
+    return chunks;
+}
+function collectStyleDeclarations(merged, value) {
     if (value == null || value === false)
-        return out;
+        return;
     if (typeof value === 'string') {
-        for (const chunk of value.split(';')) {
+        for (const chunk of splitStyleDeclarations(value)) {
             const idx = chunk.indexOf(':');
             if (idx < 0)
                 continue;
-            const key = chunk.slice(0, idx).trim();
-            const val = chunk.slice(idx + 1).trim();
-            if (key)
-                out[key] = val;
+            const key = normalizeStyleKey(chunk.slice(0, idx));
+            if (!key)
+                continue;
+            merged.set(key, [chunk.slice(idx + 1).trim()]);
         }
-        return out;
+        return;
     }
-    if (typeof value === 'object' && !Array.isArray(value)) {
-        for (const [key, raw] of Object.entries(value)) {
-            if (raw == null || raw === false)
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectStyleDeclarations(merged, item);
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const [rawKey, raw] of Object.entries(value)) {
+            const key = normalizeStyleKey(rawKey);
+            if (!key)
                 continue;
-            out[key] = String(raw);
+            const values = [];
+            pushStyleValues(values, key, raw);
+            if (values.length)
+                merged.set(key, values);
         }
     }
-    return out;
 }
 /** Merge static + dynamic style fragments; later parts override same keys. */
 export function mergeStyleParts(...parts) {
-    const merged = {};
+    const merged = new Map();
     for (const part of parts)
-        Object.assign(merged, parseStyleObject(part));
-    return Object.entries(merged)
-        .map(([key, val]) => `${key}: ${val}`)
-        .join('; ');
+        collectStyleDeclarations(merged, part);
+    const out = [];
+    for (const [key, values] of merged) {
+        for (const value of values)
+            out.push(`${key}: ${value}`);
+    }
+    return out.join('; ');
 }