@zntc/web 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ohah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @zntc/web
+
+ZNTC 의 web platform layer — dev server (HTTP/HTTPS + WebSocket HMR), HMR overlay, postcss/sass/lightningcss CSS pipeline, dev controller (file watcher + module graph).
+
+## 설치
+
+```bash
+bun add -D @zntc/web
+# 또는
+npm i -D @zntc/web
+```
+
+`@zntc/core` 가 dependency 로 자동 install 됨 (NAPI binary 포함).
+
+### Optional (CSS pipeline)
+
+```bash
+bun add -D postcss postcss-load-config sass
+```
+
+- `postcss` / `postcss-load-config` — `postcss.config.{js,ts}` 자동 탐색 / Tailwind / PostCSS plugins
+- `sass` — `.scss` / `.sass` 파일 처리
+
+## 사용
+
+`zntc dev`, `zntc preview`, `zntc build` (app mode) CLI 가 자동으로 `@zntc/web` 을 dynamic import 해서 사용. 사용자 코드에서 직접 import 할 일은 거의 없음.
+
+```bash
+bunx zntc dev       # dev server + HMR
+bunx zntc build     # production app build
+bunx zntc preview   # production preview server
+```
+
+자세한 설정: [docs/CONFIG.md](https://github.com/ohah/zts/blob/main/docs/CONFIG.md) · [docs/HMR.md](https://github.com/ohah/zts/blob/main/docs/HMR.md)
+
+## 직접 import (고급)
+
+`createAppDevController` 가 dev controller 의 main entry. 옵션 surface 가 넓고 `@zntc/core` 의 `prepareAppDevSync` 결과를 받음 — 사용 예는 [docs/HMR.md](https://github.com/ohah/zts/blob/main/docs/HMR.md) 참조.
+
+## 관련 패키지
+
+- [@zntc/core](https://npmjs.com/package/@zntc/core) — 트랜스파일러 / 번들러 코어
+- [@zntc/react-native](https://npmjs.com/package/@zntc/react-native) — RN platform layer
+- [@zntc/vite-plugin](https://npmjs.com/package/@zntc/vite-plugin) — Vite 사용 시 ZNTC transform 적용
+
+## 라이센스
+
+MIT.

package/dist/dev-controller.d.ts

@@ -0,0 +1,80 @@
+import { type BundleResult } from './inject.ts';
+import { type NodeRequire } from './style/loader.ts';
+interface ConfigEnv {
+    mode: string;
+    command?: string;
+}
+export interface AppDevControllerOptions {
+    outdir?: string | undefined;
+    base?: string | undefined;
+    publicPath?: string | undefined;
+    appRoot?: string | undefined;
+    entryHtml?: string | undefined;
+    publicDir?: string | false | undefined;
+    envDir?: string | undefined;
+    envPrefixes?: readonly string[] | undefined;
+    logLevel?: string | undefined;
+}
+export interface AppDevControllerDeps {
+    /** dev/build 의 NAPI sync wrapper — core 가 이미 세션에서 init 됐다고 가정. */
+    fallbackRequire: NodeRequire;
+    /** zntc CLI 의 node_modules — app 에 node_modules 가 없으면 symlink 대상. */
+    cliNodeModules: string;
+}
+interface PipelineCache {
+    stylePipelineFiles: string[];
+    styleSourceFiles: string[];
+}
+export interface PrepareAppCssPipelineRootOptions {
+    /** 이전 prep 의 tempRoot — incremental 재사용. null 이면 새로 mkdtemp. */
+    existingTempRoot?: string | null;
+    /** dirty 파일 path. existingTempRoot 와 함께 — 그 파일들만 sync. */
+    dirtyPaths?: readonly string[] | null;
+    /** 이전 prep 의 stylePipelineFiles + styleSourceFiles — 구조 변화 없으면 재사용. */
+    cache?: PipelineCache | null;
+}
+export interface AppCssPipelineResult {
+    tempRoot: string;
+    generatedCssAbsPaths: string[];
+    cache: PipelineCache;
+}
+export declare function cleanupPostcssTempRoot(tempRoot: string): void;
+/**
+ * postcss config + sass / css-modules 처리를 위한 temp root 준비. 입력 source 는
+ * tempRoot 로 cp 되어 mutable, 출력 (`.css` / `.module.zntc.css` / `.css.js` proxy)
+ * 도 같은 tempRoot 에 emit. 호출자가 generatedCssAbsPaths 를 받아 outdir mirror.
+ *
+ * Incremental — existingTempRoot + dirtyPaths 가 있으면 그 파일만 cp / 삭제 처리,
+ * cache 가 있으면 stylePipelineFiles / styleSourceFiles tree walk 도 skip.
+ */
+export declare function prepareAppCssPipelineRoot(root: string, outdir: string, configEnv: ConfigEnv, logLevel: string | undefined, phase: string, deps: AppDevControllerDeps, options?: PrepareAppCssPipelineRootOptions): Promise<AppCssPipelineResult | null>;
+export interface AppDevPrepareResult {
+    entryPath: string;
+}
+export interface AppDevController {
+    readonly root: string;
+    readonly outdir: string;
+    readonly base: string;
+    prepare(dirtyPaths?: readonly string[] | null): Promise<AppDevPrepareResult>;
+    afterBundle(options?: {
+        changedPath?: string | null;
+    }): Promise<{
+        deps: Set<string>;
+        dirDeps: Set<string>;
+        primaryHref: string | null;
+        processed: number;
+    }>;
+    injectBundleCssLinks(bundleResult: BundleResult): void;
+    isPostcssConfig(absPath: string): boolean;
+    isCssOnlyChange(absPath: string): boolean;
+    isSassOnlyChange(absPath: string): boolean;
+    rebuildScssIncremental(absPath: string): Promise<string | null>;
+    hrefFor(absPath: string): string;
+}
+/**
+ * dev server 의 lifecycle controller — prepare / afterBundle / HMR-related dispatch.
+ * runServe 가 watch debounce 후 controller 의 각 method 를 호출. 본 함수는 closure
+ * 로 cssDeps / pipelineRoot / pipelineCache 등 state 를 hold.
+ */
+export declare function createAppDevController(opts: AppDevControllerOptions, root: string, configEnv: ConfigEnv, deps: AppDevControllerDeps): AppDevController;
+export {};

package/dist/html-env.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HTML 안의 EJS 스타일 토큰 `<%= KEY %>` 를 환경변수 값으로 치환.
+ *
+ * - 토큰 양식: `<%=` (양쪽 공백 허용) `KEY` `%>`. `KEY` 는 `[A-Za-z_][A-Za-z0-9_]*`.
+ * - 치환 값은 `<`, `>`, `&`, `"` 를 HTML escape 한다 — `.env` 값이 attribute 안 또는 script
+ *   안에 들어가 XSS / attribute 깨짐을 만드는 것을 차단. 사용자가 의도적으로 HTML 을
+ *   넣고 싶다면 별도 옵션 (현재 미지원) 또는 inline script + import.meta.env 사용.
+ * - 허용 prefix 외 키는 원본 토큰을 그대로 두고 warning. typo / secret 노출 실수를 가시화.
+ * - 미발견 키는 빈 문자열로 치환 + warning (Vite/CRA 호환).
+ * - expression 평가 (`<%= mode === 'prod' ? ... %>`) 는 미지원 — key-only. KEY 시작이
+ *   숫자 / 기호여서 regex 가 reject.
+ */
+export declare const DEFAULT_HTML_ENV_PREFIX = "ZNTC_";
+export interface TransformHtmlEnvResult {
+    html: string;
+    changed: boolean;
+    warnings: string[];
+}
+export declare function transformHtmlEnvTokens(html: string, env: Record<string, string>, prefix?: string): TransformHtmlEnvResult;
+/**
+ * `<outdir>/index.html` 을 읽고 EJS 토큰을 치환한 결과를 다시 쓴다.
+ * ENOENT 는 silent skip — dev mode 에서 entry HTML 이 아직 없을 수 있음.
+ * `changed=false` 면 write 도 생략 — 같은 결과 재기록으로 인한 mtime 변화 / watcher 트리거 방지.
+ */
+export declare function applyHtmlEnvTokens(outdir: string, env: Record<string, string>, prefix?: string): {
+    warnings: string[];
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { APP_DEV_HMR_CLIENT_PATH, APP_DEV_HMR_WS_PATH, type BunHmrClient, createHmrChannel, createWatcher, type CreateWatcherOptions, HMR_MSG, type HmrChannel, type HmrConnectedMessage, type HmrCssUpdateMessage, type HmrError, type HmrErrorMessage, type HmrFullReloadMessage, type HmrMessage, type HmrMessageType, type WatchEventType, type WatchFn, type WatchListener, type WatcherHandle, type WatcherInstance, } from '@zntc/server';
+export { type BundleResult, injectAppDevBundleCssLinks, injectAppDevHmrClient, injectAppDevPipelineCssLinks, injectIntoDevHtml, } from './inject.ts';
+export { DEFAULT_HTML_ENV_PREFIX, type TransformHtmlEnvResult, applyHtmlEnvTokens, transformHtmlEnvTokens, } from './html-env.ts';
+export { joinUrl } from './url.ts';
+export { isCssIdent, isCssIdentStart, skipCssString, skipCssUrl, startsWithCssIdent, } from './style/css-parser.ts';
+export { collectAppFiles, type CollectAppFilesOptions, requireFromAppOrFallback, } from './style/loader.ts';
+export { type AppDevPostcssOptions, type AppDevPostcssResult, collectPostcssMessages, findPostcssConfig, isCssFile, isPostcssConfigFile, loadPostcssConfig, logPostcssProcessed, type PostcssMessage, POSTCSS_CONFIG_NAMES, runPostcssForAppDev, runPostcssIfConfigured, } from './style/postcss.ts';
+export { buildCssPreprocessorProxy, CSS_PREPROCESSOR_EXTENSIONS, compileSassFile, cssPreprocessorOutputPath, cssPreprocessorProxyPath, isCssModulePreprocessorFile, isCssPreprocessorFile, isStyleReferenceSource, loadSassCompiler, rewriteSassReferences, transformCssPreprocessors, type TransformCssPreprocessorOptions, } from './style/sass.ts';
+export { buildCssModuleProxy, collectCssModuleClasses, type CssModuleClassToken, cssModuleGeneratedCssPath, cssModuleLocalName, cssModuleProxyPath, isCssModuleFile, isValidExportName, rewriteCssModuleClasses, rewriteCssModuleReferences, scanCssModuleClassTokens, transformCssModules, type TransformCssModulesOptions, } from './style/css-modules.ts';
+export { type AppCssPipelineResult, type AppDevController, type AppDevControllerDeps, type AppDevControllerOptions, cleanupPostcssTempRoot, createAppDevController, prepareAppCssPipelineRoot, type PrepareAppCssPipelineRootOptions, } from './dev-controller.ts';
+export { APP_DEV_HMR_CLIENT } from '../runtime/dev-overlay-client.mjs';