@zntc/web 0.1.1 → 0.1.2

package/dist/inject.d.ts

@@ -12,6 +12,21 @@ export interface BundleResult {
 export declare function injectIntoDevHtml(outdir: string, build: (html: string) => string | null): void;
 /** `<script type="module" src="/__zntc_app_dev_hmr__"></script>` 를 head 에 1회 삽입. */
 export declare function injectAppDevHmrClient(outdir: string): void;
+/**
+ * React Fast Refresh preamble `<script src="/__zntc_react_refresh__"></script>` 를 1회 삽입.
+ * ⚠️ **첫 `<script` 앞**에 넣는다 — classic(non-module) 스크립트라 파싱 중 동기 실행되어
+ * `injectIntoGlobalHook(window)` 가 React 를 import 하는 (deferred) module 스크립트보다 *먼저*
+ * 끝나야 reconciler 패치가 유효하다. injectIntoDevHtml(=`</head>` 앞 삽입)을 안 쓰는 이유.
+ */
+export declare function injectAppDevReactRefreshPreamble(outdir: string): void;
 export declare function injectAppDevBundleCssLinks(outdir: string, base: string | undefined, bundleResult: BundleResult | null | undefined): void;
+/**
+ * #3813 — outdir 의 `.css` 파일을 file system 스캔해 HTML `<link>` 주입. `injectAppDevBundleCssLinks`
+ * 가 `bundleResult.outputFiles` 를 받는 것과 달리 file system 기반. caller (`runServe`) 가
+ * native watch onRebuild 에서 호출 — bundleResult 가 없는 graphChanged 경로의 stale link 회귀
+ * 가드. outdir 의 first-level `*.css` 만 스캔 (chunk subdirectory 미포함 — bundler 의 entry_names
+ * `[dir]/[name]` default 가 emit 한 결과 위치 기준).
+ */
+export declare function injectAppDevBundleCssLinksFromOutdir(outdir: string, base: string | undefined): void;
 export declare function injectAppDevPipelineCssLinks(outdir: string, base: string | undefined, cssRelPaths: readonly string[]): void;
 export {};

package/dist/react-refresh-preamble.d.ts

@@ -0,0 +1,8 @@
+/**
+ * react-refresh 런타임 소스를 글로벌 바인딩 + injectIntoGlobalHook 으로 감싼 preamble 문자열.
+ *  - react-refresh 설치됨 → 실제 preamble.
+ *  - react 는 있으나 react-refresh 없음 → noop + 설치 경고(=React 앱인데 FR 못 켬).
+ *  - react 도 없음 → `null`(비-React 앱 — 호출자가 주입/서빙 스킵, 경고 없음).
+ * @param rootDir 앱 루트(여기 node_modules 기준으로 resolve).
+ */
+export declare function buildReactRefreshPreamble(rootDir: string): string | null;

package/dist/style/postcss.d.ts

@@ -38,12 +38,44 @@ interface ConfigEnv {
  * `fallbackRequire` 는 caller 의 CLI context — postcss/postcss-load-config 를
  * app 이 갖지 않을 때 fallback (e.g. ZNTC CLI 의 node_modules).
  */
-export declare function loadPostcssConfig(root: string, configEnv: ConfigEnv, fallbackRequire: NodeRequire): Promise<LoadedPostcss | null>;
+export declare function loadPostcssConfig(root: string, configEnv: ConfigEnv, fallbackRequire: NodeRequire, 
+/** issue #3857 /code-review max #1 — postcss / postcss-load-config 의
+ *  require base. config search 가 monorepo root 인 경우에도 module require
+ *  는 app root 가 정상 (pnpm strict / nohoist 환경에서 monorepo root 에
+ *  postcss 미설치 가능). 미지정 시 root 인자 사용 — 기존 동작 유지. */
+requireBase?: string): Promise<LoadedPostcss | null>;
 /**
  * `cssDir` 의 모든 CSS 파일 (skipDir 제외) 에 postcss 실행 → in-place 덮어쓰기.
  * postcss config 가 없으면 no-op. `runPostcssForAppDev` 와 달리 outdir 분리 안 함.
+ *
+ * `override` 가 truthy 면 자동 발견 skip — 사용자 explicit `plugins: [css({
+ * postcss: {...override} })]` 의 caller-side pre-warm path (RFC #3833 v3 D1a'').
+ * Vite parity: `override.plugins` 가 빈 배열이어도 explicit no-op 으로 처리
+ * (auto-discover 로 fallback 안 함). `postcss` 자체는 동일 fallback chain 으로
+ * require — 미설치 시 logLevel != silent 면 warn 출력 후 skip (override path
+ * 가 silently no-op 안 되도록 가시성 확보).
  */
-export declare function runPostcssIfConfigured(root: string, cssDir: string, skipDir: string | null, configEnv: ConfigEnv, logLevel: string | undefined, fallbackRequire: NodeRequire): Promise<void>;
+export interface RunPostcssIfConfiguredResult {
+    /** issue #3850 — PostCSS message 의 dep tracking. tailwind @source 등의
+     *  file dependency. caller (prepareAppCssPipelineRoot) 가 보존 후 dev path
+     *  의 skipPostcssRun 가 watch trigger 정합 위해 사용. */
+    deps: Set<string>;
+    /** issue #3850 — PostCSS message 의 dir-dep tracking. tailwind v4 의
+     *  @source "../html" 같은 directory watch. */
+    dirDeps: Set<string>;
+}
+export declare function runPostcssIfConfigured(root: string, cssDir: string, skipDir: string | null, configEnv: ConfigEnv, logLevel: string | undefined, fallbackRequire: NodeRequire, override?: {
+    plugins: unknown[];
+    options?: Record<string, unknown>;
+    /** issue #3851 — css({root}) 의 root override. postcss module require 의
+     *  base. 미지정 시 root 인자 사용. */
+    root?: string;
+} | null, 
+/** issue #3857 — css({root}) 단독 명시 시 auto-discover path 의 search base.
+ *  override 없을 때 loadPostcssConfig(cssAutoDiscoverRoot ?? root) 로 호출 →
+ *  postcss.config 가 monorepo root 에 있고 app 이 sub-package 인 시나리오 cover.
+ *  미지정 시 root 인자 사용 — 기존 동작 유지. */
+cssAutoDiscoverRoot?: string | null): Promise<RunPostcssIfConfiguredResult>;
 export interface AppDevPostcssOptions {
     root: string;
     outdir: string;
@@ -52,6 +84,28 @@ export interface AppDevPostcssOptions {
     base: string | undefined;
     changedPath?: string | null;
     fallbackRequire: NodeRequire;
+    /** caller-side pre-warm 으로 전달되는 PostCSS override (RFC #3833 v3 D1a''
+     *  Phase 2). build path 의 `runPostcssIfConfigured` 와 동일 시맨틱 — truthy
+     *  면 자동발견 skip, plugins.length === 0 면 explicit no-op. issue #3851:
+     *  root override 도 routing (postcss require base). */
+    postcssOverride?: {
+        plugins: unknown[];
+        options?: Record<string, unknown>;
+        root?: string;
+    } | null;
+    /** dev path zero-config double-pass 회피 (issue #3847). controller 의
+     *  prepare 가 PostCSS 처리 (auto-discover 또는 override) 했음을 caller 가
+     *  알린 경우 true — runPostcssForAppDev 가 PostCSS 호출 skip + sourceRoot
+     *  의 .css 를 outdir 로 mirror (PostCSS 미적용, 이미 처리된 결과 그대로).
+     *  cssDeps 는 raw root path 로 유지 (watch trigger 정합). */
+    skipPostcssRun?: boolean;
+    /** skipPostcssRun=true 시 mirror 의 source root (prepare 의 tempRoot 또는
+     *  raw root). 미지정 시 root 사용. controller 가 pipelineRoot 전달. */
+    sourceRoot?: string;
+    /** issue #3857 — auto-discover path 의 findPostcssConfig/loadPostcssConfig
+     *  search base. monorepo edge: app 이 sub-package, postcss.config 가
+     *  monorepo root. 미지정 시 root 인자 사용. */
+    cssAutoDiscoverRoot?: string | null;
 }
 export interface AppDevPostcssResult {
     deps: Set<string>;

package/dist/style/sass.d.ts

@@ -9,6 +9,9 @@ interface SassCompileOptions {
 }
 interface SassCompileResult {
     css: string;
+    /** dart-sass 가 컴파일에 사용한 전이 @import/@use URL 목록(자기 자신 포함). dev watch 의
+     *  reverse-dep 추적용 — partial(`_x.scss`) 변경 시 이를 import 한 root scss 를 재컴파일 (#71). */
+    loadedUrls?: URL[];
 }
 export declare const CSS_PREPROCESSOR_EXTENSIONS: ReadonlySet<string>;
 export declare function isCssPreprocessorFile(path: string): boolean;
@@ -40,6 +43,9 @@ export interface TransformCssPreprocessorOptions {
     dirtyOnly?: ReadonlySet<string> | null;
     /** dirty source files — `rewriteSassReferences` 의 대상 한정. null 이면 sourceFiles 전체. */
     dirtySources?: readonly string[] | null;
+    /** 컴파일한 파일별 전이 @import/@use 의존(loadedUrls)을 보고하는 콜백. dev watch 가
+     *  reverse-dep 맵을 구축해 partial 변경 시 root scss 를 재컴파일하는 데 쓴다 (#71). */
+    onDeps?: (file: string, loadedUrls: readonly URL[]) => void;
 }
 /**
  * `files` (Sass/SCSS 입력) 를 컴파일해 같은 path 의 `.css` + `.css.js` proxy 생성.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zntc/web",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "ZNTC web platform — dev server + HMR overlay + postcss/sass pipeline + dev controller",
   "keywords": [
     "bundler",
@@ -35,21 +35,25 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./css": {
+      "types": "./dist/css/index.d.ts",
+      "import": "./dist/css/index.js"
     }
   },
   "scripts": {
-    "build:bundle": "node ../core/bin/zntc.mjs --bundle src/index.ts --outfile dist/index.js --format=esm --target=node --conditions=source --external @zntc/core --external postcss --external postcss-load-config --external sass",
+    "build:bundle": "node ../core/bin/zntc.mjs --bundle src/index.ts --outfile dist/index.js --format=esm --target=node --conditions=source --external @zntc/core --external postcss --external postcss-load-config --external sass && node ../core/bin/zntc.mjs --bundle src/css/index.ts --outfile dist/css/index.js --format=esm --target=node --conditions=source --external @zntc/core --external postcss --external postcss-load-config --external sass && node -e \"require('node:fs').copyFileSync('runtime/dev-overlay-client.raw.js','dist/dev-overlay-client.raw.js')\"",
     "build:dts": "bun x tsc -b",
     "build": "bun run build:bundle && bun run build:dts",
     "test": "bun test --timeout 10000",
-    "prepublishOnly": "bun run build && bunx publint --strict --level error ."
+    "prepublishOnly": "bun run build && node -e \"require('node:fs').statSync('dist/dev-overlay-client.raw.js')\" && bunx publint --strict --level error ."
   },
   "dependencies": {
-    "@zntc/core": "0.1.1"
+    "@zntc/core": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^25.5.2",
-    "@zntc/server": "0.1.1"
+    "@zntc/server": "0.1.2"
   },
   "optionalDependencies": {
     "postcss": "^8.5.8",