@zntc/web 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +48 -0
  3. package/dist/dev-controller.d.ts +80 -0
  4. package/dist/html-env.d.ts +27 -0
  5. package/dist/index.d.ts +11 -0
  6. package/dist/index.js +1124 -0
  7. package/dist/inject.d.ts +17 -0
  8. package/dist/style/css-modules.d.ts +52 -0
  9. package/dist/style/css-parser.d.ts +15 -0
  10. package/dist/style/loader.d.ts +28 -0
  11. package/dist/style/postcss.d.ts +68 -0
  12. package/dist/style/sass.d.ts +52 -0
  13. package/dist/url.d.ts +2 -0
  14. package/package.json +62 -0
package/dist/inject.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ interface BundleOutputFile {
2
+ path?: string;
3
+ }
4
+ export interface BundleResult {
5
+ outputFiles?: readonly BundleOutputFile[];
6
+ }
7
+ /**
8
+ * `<outdir>/index.html` 을 읽어 `build(html)` 결과 (`<head>` 직전 / `<script>`
9
+ * 직전 삽입할 tag string) 를 끼워 넣는다. ENOENT 면 silent skip — dev mode 에서
10
+ * 아직 entry HTML 이 없을 수 있음.
11
+ */
12
+ export declare function injectIntoDevHtml(outdir: string, build: (html: string) => string | null): void;
13
+ /** `<script type="module" src="/__zntc_app_dev_hmr__"></script>` 를 head 에 1회 삽입. */
14
+ export declare function injectAppDevHmrClient(outdir: string): void;
15
+ export declare function injectAppDevBundleCssLinks(outdir: string, base: string | undefined, bundleResult: BundleResult | null | undefined): void;
16
+ export declare function injectAppDevPipelineCssLinks(outdir: string, base: string | undefined, cssRelPaths: readonly string[]): void;
17
+ export {};
package/dist/style/css-modules.d.ts ADDED
@@ -0,0 +1,52 @@
1
+ /** `.module.css` 종결만 인식 — case-sensitive (Vite/webpack css-loader 컨벤션 일치). */
2
+ export declare function isCssModuleFile(path: string): boolean;
3
+ export declare function cssModuleGeneratedCssPath(file: string): string;
4
+ /**
5
+ * `x.module.css → x.module.css.js` proxy. sass 의 `cssPreprocessorProxyPath`
6
+ * (`x.scss → x.css.js`) 와 출력 형태가 다른 이유: CSS Modules 는 원본 확장자
7
+ * 보존이 import resolver 에 필요 (`.module.css` 를 import 한 caller 의 type
8
+ * 추론과 일치).
9
+ */
10
+ export declare function cssModuleProxyPath(file: string): string;
11
+ /**
12
+ * `${fileName}_${safeLocal}__${hash8}` 형식의 unique class name.
13
+ * hash 8 chars (~48 bits) 면 100k 클래스에서도 birthday collision <0.001%.
14
+ */
15
+ export declare function cssModuleLocalName(root: string, file: string, local: string): string;
16
+ export interface CssModuleClassToken {
17
+ start: number;
18
+ end: number;
19
+ local: string;
20
+ }
21
+ /**
22
+ * CSS 안의 일반 `.class-name` 토큰 위치를 수집. `:global`/`:local` 슈도, `composes:`
23
+ * 룰, `@keyframes` 이름 scoping 등 고급 CSS Modules 스펙은 미지원.
24
+ */
25
+ export declare function scanCssModuleClassTokens(css: string): CssModuleClassToken[];
26
+ export declare function collectCssModuleClasses(css: string): string[];
27
+ export declare function rewriteCssModuleClasses(css: string, mapping: Record<string, string>): string;
28
+ export declare function isValidExportName(name: string): boolean;
29
+ /**
30
+ * proxy module — class-name map 의 default export 와 valid identifier named
31
+ * export 를 emit. 실제 CSS 는 generated `.module.zntc.css` 가 `<link>` 로 도달.
32
+ */
33
+ export declare function buildCssModuleProxy(generatedCssPath: string, mapping: Record<string, string>): string;
34
+ /**
35
+ * `import \"x.module.css\"` → `\"x.module.css.js\"` proxy redirect.
36
+ * HTML 의 `<link href=\"x.module.css\">` 는 일반 CSS 로 취급되므로 skip.
37
+ */
38
+ export declare function rewriteCssModuleReferences(sourceFiles: readonly string[]): void;
39
+ export interface TransformCssModulesOptions {
40
+ /** dirty Set — 그 안에 들어있는 파일만 재처리. null 이면 전체. */
41
+ dirtyOnly?: ReadonlySet<string> | null;
42
+ /** dirty source files — `rewriteCssModuleReferences` 의 대상 한정. */
43
+ dirtySources?: readonly string[] | null;
44
+ }
45
+ /**
46
+ * `moduleFiles` 의 `.module.css` 를 generated `.module.zntc.css` + `.module.css.js`
47
+ * proxy 로 변환. `styleSources` 의 `import \"x.module.css\"` 는 proxy 로 redirect.
48
+ *
49
+ * dirtyOnly 가 주어지면 그 안에 든 파일만 재처리하지만 반환은 전체 list —
50
+ * incremental rebuild 시에도 caller 가 일관된 set 을 받도록.
51
+ */
52
+ export declare function transformCssModules(root: string, moduleFiles: readonly string[], styleSources: readonly string[], logLevel: string | undefined, options?: TransformCssModulesOptions): string[];
package/dist/style/css-parser.d.ts ADDED
@@ -0,0 +1,15 @@
1
+ /**
2
+ * `start` 가 가리키는 css string literal 끝 다음 위치 반환. `\` escape 와
3
+ * 종료 quote 를 인식. 닫히지 않은 문자열은 css 끝까지 skip.
4
+ */
5
+ export declare function skipCssString(css: string, start: number, quote: string): number;
6
+ /**
7
+ * `url(...)` 안의 끝 `)` 다음 위치 반환. 인용된 url 도 string skip 으로 안전 처리.
8
+ */
9
+ export declare function skipCssUrl(css: string, start: number): number;
10
+ /** `css` 의 `offset` 부터 `value` 와 case-insensitive 일치하는지 확인. */
11
+ export declare function startsWithCssIdent(css: string, offset: number, value: string): boolean;
12
+ /** CSS identifier 시작 가능 문자 (`_`, `A-Z`, `a-z`). */
13
+ export declare function isCssIdentStart(ch: string): boolean;
14
+ /** CSS identifier 내부 가능 문자 (시작 문자 + `-` + `0-9`). */
15
+ export declare function isCssIdent(ch: string): boolean;
package/dist/style/loader.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ export interface NodeRequire {
2
+ (specifier: string): unknown;
3
+ }
4
+ /**
5
+ * `root` 의 package.json 기준 `require` 로 specifier 를 로드, MODULE_NOT_FOUND
6
+ * 시 fallbackRequire 로 fallback. postcss/sass 같은 optional dev deps 가 app
7
+ * 또는 CLI 어느 쪽에 있는지 모를 때 양쪽 모두 시도.
8
+ */
9
+ export declare function requireFromAppRoot(root: string, fallbackRequire: NodeRequire, specifier: string): unknown;
10
+ /**
11
+ * App 의 `require` 로 먼저 시도, MODULE_NOT_FOUND 발생 시 fallback `require` 로
12
+ * 재시도. zntc dev/build pipeline 의 plugin / preprocessor 로딩 (postcss/sass 등)
13
+ * 에서 \"app deps 우선, CLI deps fallback\" 패턴을 명시화.
14
+ */
15
+ export declare function requireFromAppOrFallback(requireFromApp: NodeRequire, fallbackRequire: NodeRequire, specifier: string): unknown;
16
+ export interface CollectAppFilesOptions {
17
+ /** 이 디렉토리 (절대 또는 상대 경로) 와 일치하는 sub-tree 는 walk 안 함. */
18
+ skipDir?: string | null;
19
+ /** file 마다 호출, true 면 결과에 포함. default: 모든 파일 포함. */
20
+ predicate?: (path: string) => boolean;
21
+ }
22
+ /**
23
+ * `dir` 의 모든 파일을 재귀적으로 수집. `node_modules` 와 `.git` 은 자동 skip.
24
+ * 파일 시스템 IO 만 사용 — 외부 모듈 의존 없음.
25
+ *
26
+ * @returns 디렉토리가 없으면 빈 배열 (ENOENT silent). ENOTDIR/EACCES 등 다른 IO 에러는 throw.
27
+ */
28
+ export declare function collectAppFiles(dir: string, options?: CollectAppFilesOptions): string[];
package/dist/style/postcss.d.ts ADDED
@@ -0,0 +1,68 @@
1
+ import { type NodeRequire } from './loader.ts';
2
+ export declare const POSTCSS_CONFIG_NAMES: readonly string[];
3
+ export declare const isCssFile: (path: string) => boolean;
4
+ export declare function isPostcssConfigFile(path: string): boolean;
5
+ /** `root` 디렉토리에 postcss config 가 있으면 절대 path 반환, 없으면 null. */
6
+ export declare function findPostcssConfig(root: string): string | null;
7
+ export interface PostcssMessage {
8
+ type?: string;
9
+ file?: unknown;
10
+ dir?: unknown;
11
+ directory?: unknown;
12
+ }
13
+ /** postcss result.messages 에서 dep 트래킹용 file/dir 항목을 set 에 누적. */
14
+ export declare function collectPostcssMessages(messages: readonly PostcssMessage[] | null | undefined, deps: Set<string>, dirDeps: Set<string>): void;
15
+ export declare function logPostcssProcessed(logLevel: string | undefined, count: number, configFile: string | null | undefined): void;
16
+ interface LoadedPostcss {
17
+ postcss: (plugins: unknown[]) => {
18
+ process: (input: string, options: unknown) => Promise<PostcssResult>;
19
+ };
20
+ plugins: unknown[];
21
+ options: Record<string, unknown>;
22
+ configFile: string | null;
23
+ }
24
+ interface PostcssResult {
25
+ css: string;
26
+ map?: {
27
+ toString(): string;
28
+ };
29
+ messages?: PostcssMessage[];
30
+ }
31
+ interface ConfigEnv {
32
+ mode: string;
33
+ }
34
+ /**
35
+ * postcss + postcss-load-config 를 app-first / fallback-second 로 require 후
36
+ * config 로드. config 없거나 plugin 0 이면 null.
37
+ *
38
+ * `fallbackRequire` 는 caller 의 CLI context — postcss/postcss-load-config 를
39
+ * app 이 갖지 않을 때 fallback (e.g. ZNTC CLI 의 node_modules).
40
+ */
41
+ export declare function loadPostcssConfig(root: string, configEnv: ConfigEnv, fallbackRequire: NodeRequire): Promise<LoadedPostcss | null>;
42
+ /**
43
+ * `cssDir` 의 모든 CSS 파일 (skipDir 제외) 에 postcss 실행 → in-place 덮어쓰기.
44
+ * postcss config 가 없으면 no-op. `runPostcssForAppDev` 와 달리 outdir 분리 안 함.
45
+ */
46
+ export declare function runPostcssIfConfigured(root: string, cssDir: string, skipDir: string | null, configEnv: ConfigEnv, logLevel: string | undefined, fallbackRequire: NodeRequire): Promise<void>;
47
+ export interface AppDevPostcssOptions {
48
+ root: string;
49
+ outdir: string;
50
+ configEnv: ConfigEnv;
51
+ logLevel: string | undefined;
52
+ base: string | undefined;
53
+ changedPath?: string | null;
54
+ fallbackRequire: NodeRequire;
55
+ }
56
+ export interface AppDevPostcssResult {
57
+ deps: Set<string>;
58
+ dirDeps: Set<string>;
59
+ primaryHref: string | null;
60
+ processed: number;
61
+ }
62
+ /**
63
+ * Dev 모드 — `root` 의 CSS 파일들을 `outdir` 의 같은 rel path 로 emit (postcss
64
+ * pipeline 적용). config 없으면 첫 CSS 의 primaryHref 만 반환. 단일 변경 (.css)
65
+ * 이면 해당 파일만 reprocess, 그 외엔 전체.
66
+ */
67
+ export declare function runPostcssForAppDev(options: AppDevPostcssOptions): Promise<AppDevPostcssResult>;
68
+ export {};
package/dist/style/sass.d.ts ADDED
@@ -0,0 +1,52 @@
1
+ import { type NodeRequire } from './loader.ts';
2
+ interface SassCompiler {
3
+ compile: (file: string, options: SassCompileOptions) => SassCompileResult;
4
+ }
5
+ interface SassCompileOptions {
6
+ style?: 'expanded' | 'compressed';
7
+ loadPaths?: string[];
8
+ sourceMap?: boolean;
9
+ }
10
+ interface SassCompileResult {
11
+ css: string;
12
+ }
13
+ export declare const CSS_PREPROCESSOR_EXTENSIONS: ReadonlySet<string>;
14
+ export declare function isCssPreprocessorFile(path: string): boolean;
15
+ export declare function isCssModulePreprocessorFile(path: string): boolean;
16
+ export declare function cssPreprocessorOutputPath(file: string): string;
17
+ export declare function cssPreprocessorProxyPath(file: string): string;
18
+ /** Sass compiler 를 app-first / fallback-second 로 require. 모듈 미설치 시 친화 메시지 throw. */
19
+ export declare function loadSassCompiler(root: string, fallbackRequire: NodeRequire): SassCompiler;
20
+ /**
21
+ * Sass 옵션 single source — full transform / dev fast-path / 어느 caller 가 부르
22
+ * 든 같은 옵션 사용 보장. drift 회피용 helper.
23
+ */
24
+ export declare function compileSassFile(sass: SassCompiler, file: string, loadRoot: string): SassCompileResult;
25
+ export declare function isStyleReferenceSource(path: string): boolean;
26
+ /**
27
+ * HTML 은 `<link href=\"x.scss\">` 를 그대로 컴파일된 CSS 로, JS/TS 는 `.css.js`
28
+ * proxy (`import \"./generated.css\"` 한 줄) 로 rewrite. CSS Modules 의 .module.css
29
+ * rewriter 는 HTML 미지원이라 별도 함수 (rewriteCssModuleReferences).
30
+ */
31
+ export declare function rewriteSassReferences(sourceFiles: readonly string[]): void;
32
+ /**
33
+ * `cssPath` 의 basename 만 import 하는 한 줄 ESM proxy. bundler 가 module graph
34
+ * 에서 CSS 를 side-effect 로 추적하기 위한 entry — 실제 CSS 는 build 시 chunk
35
+ * 로 emit, dev 시 컴파일된 CSS 를 outdir 로 mirror 후 HTML `<link>` 로 서빙.
36
+ */
37
+ export declare function buildCssPreprocessorProxy(cssPath: string): string;
38
+ export interface TransformCssPreprocessorOptions {
39
+ /** dirty Set — 그 안에 들어있는 파일만 재컴파일. null 이면 전체. */
40
+ dirtyOnly?: ReadonlySet<string> | null;
41
+ /** dirty source files — `rewriteSassReferences` 의 대상 한정. null 이면 sourceFiles 전체. */
42
+ dirtySources?: readonly string[] | null;
43
+ }
44
+ /**
45
+ * `files` (Sass/SCSS 입력) 를 컴파일해 같은 path 의 `.css` + `.css.js` proxy 생성.
46
+ * `sourceFiles` (참조 HTML/JS/TS) 의 `import \"x.scss\"` 도 새 확장자로 rewrite.
47
+ *
48
+ * dirtyOnly 가 주어지면 그 안에 든 파일만 재컴파일하지만 반환 path 는 전체 (outdir
49
+ * mirror 가 stale 안 되도록).
50
+ */
51
+ export declare function transformCssPreprocessors(root: string, files: readonly string[], sourceFiles: readonly string[], logLevel: string | undefined, fallbackRequire: NodeRequire, options?: TransformCssPreprocessorOptions): string[];
52
+ export {};
package/dist/url.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ /** dev server / postcss / inject 공통 — base + rel path concat URL helper. */
2
+ export declare function joinUrl(base: string | undefined, rel: string): string;
package/package.json ADDED
@@ -0,0 +1,62 @@
1
+ {
2
+ "name": "@zntc/web",
3
+ "version": "0.1.0",
4
+ "description": "ZNTC web platform — dev server + HMR overlay + postcss/sass pipeline + dev controller",
5
+ "keywords": [
6
+ "bundler",
7
+ "dev-server",
8
+ "hmr",
9
+ "postcss",
10
+ "sass",
11
+ "tailwind",
12
+ "transpiler",
13
+ "vite",
14
+ "zntc"
15
+ ],
16
+ "homepage": "https://ohah.github.io/zntc",
17
+ "bugs": {
18
+ "url": "https://github.com/ohah/zntc/issues"
19
+ },
20
+ "license": "MIT",
21
+ "author": "ohah",
22
+ "repository": {
23
+ "type": "git",
24
+ "url": "git+https://github.com/ohah/zntc.git",
25
+ "directory": "packages/web"
26
+ },
27
+ "files": [
28
+ "dist/",
29
+ "README.md"
30
+ ],
31
+ "type": "module",
32
+ "main": "./dist/index.js",
33
+ "types": "./dist/index.d.ts",
34
+ "exports": {
35
+ ".": {
36
+ "types": "./dist/index.d.ts",
37
+ "import": "./dist/index.js"
38
+ }
39
+ },
40
+ "scripts": {
41
+ "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",
42
+ "build:dts": "bun x tsc -b",
43
+ "build": "bun run build:bundle && bun run build:dts",
44
+ "test": "bun test --timeout 10000",
45
+ "prepublishOnly": "bun run build && bunx publint --strict --level error ."
46
+ },
47
+ "dependencies": {
48
+ "@zntc/core": "workspace:*"
49
+ },
50
+ "devDependencies": {
51
+ "@types/node": "^25.5.2",
52
+ "@zntc/server": "workspace:*"
53
+ },
54
+ "optionalDependencies": {
55
+ "postcss": "^8.5.8",
56
+ "postcss-load-config": "^6.0.1",
57
+ "sass": "^1.99.0"
58
+ },
59
+ "engines": {
60
+ "node": ">=24.0.0"
61
+ }
62
+ }