@teacss/inspector 0.9.3 → 0.10.2

package/dist/client/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>TeaCSS Inspector</title>
-    <script type="module" crossorigin src="/__teacss/assets/index-BMcqNdMD.js"></script>
-    <link rel="stylesheet" crossorigin href="/__teacss/assets/index-QRwAp_3w.css">
+    <script type="module" crossorigin src="/__teacss/assets/index-DHyQVuSN.js"></script>
+    <link rel="stylesheet" crossorigin href="/__teacss/assets/index-BsirYgOp.css">
   </head>
   <body>
     <div id="app"></div>

package/dist/index.d.ts

@@ -1,115 +1,12 @@
-import { TeacssGenerator, TeacssPluginContext } from "@teacss/core";
-import { IncomingMessage, ServerResponse } from "node:http";
-import { Plugin } from "vite";
-//#region src/types.d.ts
-/** A single matched token (utility/class) and what it produced. */
-export interface MatchedToken {
-  /** The raw token as written in source, e.g. `bg-color:red-500`. */
-  token: string;
-  /** The generated CSS declarations (rule bodies joined), for preview. */
-  css: string;
-  /** How many times the token resolved across the analyzed input. */
-  count: number;
-  /** A coarse family used to group tokens in the UI (the property prefix). */
-  category: string;
-  /** Source module ids that contained this token (empty for the REPL). */
-  modules: string[];
-}
-/** One output layer and its CSS. */
-export interface LayerCss {
-  name: string;
-  css: string;
-}
-/** The common payload behind /overview, /module and /repl. */
-export interface GenerateResultDTO {
-  /** Full generated CSS (all layers concatenated in order). */
-  css: string;
-  /** Per-layer CSS, in layer order. */
-  layers: LayerCss[];
-  /** Matched tokens, sorted by descending count. */
-  matched: MatchedToken[];
-}
-/** A safe, acyclic summary of the resolved config (no live objects). */
-export interface ConfigSummary {
-  presets: string[];
-  /** `[name, order]` pairs, sorted by order. */
-  layers: [string, number][];
-  rules: number;
-  shortcuts: number;
-  themeKeys: string[];
-}
-/** GET / — project + config overview chrome. */
-export interface ProjectInfo {
-  version: string;
-  root: string;
-  /** Scanned module ids (sorted). */
-  modules: string[];
-  /** Config entry/source files backing the resolved config. */
-  configSources: string[];
-  config: ConfigSummary;
-}
-/** GET /overview — whole-project generated CSS + analysis. */
-export interface OverviewInfo extends GenerateResultDTO {
-  gzipSize: number;
-}
-/** GET /module?id= — a single module's source + what it generated. */
-export interface ModuleInfo extends GenerateResultDTO {
-  id: string;
-  code: string;
-  gzipSize: number;
-}
-/** GET /repl?token= — generate CSS from arbitrary input. */
-export type ReplResult = GenerateResultDTO;
-/** Mount paths (also used to build client asset URLs). */
-export declare const CLIENT_BASE = "__teacss";
-export declare const API_BASE = "__teacss_api";
-//#endregion
-//#region src/analyzer.d.ts
-/** Map of source-module id → the tokens extracted from it. */
-type ModuleTokens = Map<string, Set<string>>;
-/** Coarse grouping family for a token: its property prefix, else the keyword stem. */
-export declare function categoryOf(token: string): string;
-interface GenerateDTOOptions {
-  /** Module attribution source; when given, each matched token lists its files. */
-  moduleTokens?: ModuleTokens;
-  /** Apply the config safelist (REPL toggle). */
-  safelist?: boolean;
-  /** Module id for scoped generation. */
-  id?: string;
-}
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type Project } from "@teacss/engine";
+export type { ModuleTokens, ProjectResponse, ReplRequest } from "./types.js";
+/** Connect-compatible: `server.middlewares.use("/__teacss", createInspectorMiddleware(project))`. */
+export type InspectorMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
 /**
- * Run the generator over `input` (a token set or a raw string the generator
- * auto-extracts) and shape the result into the inspector's wire DTO: full CSS,
- * per-layer CSS, and the matched tokens with declaration bodies, counts, and
- * (optionally) which modules used each.
+ * v10.2 §3.6: `/api/project`, `/api/modules`, `/api/css`, `/api/stats` and `POST /api/repl` read `project` through napi;
+ * v10.3 §5 adds `/api/token/<token>` and `/api/suggest?q=`, and `/api/module?id=` generates one module's token list.
+ * Every other path is the static UI. Only loopback requests are answered (403 otherwise).
  */
-export declare function generateDTO(generator: TeacssGenerator, input: Set<string> | string, options?: GenerateDTOOptions): Promise<GenerateResultDTO>;
-//#endregion
-//#region src/index.d.ts
-/** One scanned module the inspector tracks: its source + the tokens it used. */
-interface ModuleEntry {
-  code: string;
-  tokens: Set<string>;
-}
-/** The inspector's per-module state, shared between the plugin and the API. */
-export interface InspectorStore {
-  /** Clean id (no `?query`) → entry. */
-  modules: Map<string, ModuleEntry>;
-  /** Bumped whenever `modules` or the config changes — keys the overview cache. */
-  version: () => number;
-}
-/**
- * A connect-style request handler serving the inspector's JSON API. Reads the
- * live generator/context plus the per-module `store` the plugin tracks. Mount it
- * under `/${API_BASE}`. The `/overview` response is cached on the store version.
- */
-export declare function createInspectorApi(ctx: TeacssPluginContext, store: InspectorStore): (req: IncomingMessage, res: ServerResponse, next: () => void) => Promise<void>;
-/**
- * Vite plugin: mounts the TeaCSS inspector on the dev server. Add it alongside
- * `pluginTeacss()` — it discovers the live context through that plugin's `teacss:api`
- * and serves the UI at `/${CLIENT_BASE}` with its JSON API at `/${API_BASE}`.
- * Dev-only (`apply: "serve"`).
- */
-export declare function pluginInspector(): Plugin;
-//#endregion
-export type { ModuleTokens };
+export declare function createInspectorMiddleware(project: Project): InspectorMiddleware;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,2 +1,132 @@
-import{fileURLToPath as e}from"node:url";import{gzipSync as t}from"node:zlib";import{SKIP_END_COMMENT as n,SKIP_START_COMMENT as r}from"@teacss/core";import i from"sirv";import{BlockList as a,isIP as o}from"node:net";const s=new a;s.addSubnet(`127.0.0.0`,8,`ipv4`),s.addAddress(`::1`,`ipv6`);function c(e){if(!e)return!1;let t=e.startsWith(`[`)&&e.endsWith(`]`)?e.slice(1,-1):e,n=o(t);return n?s.check(t,n===4?`ipv4`:`ipv6`):!1}function l(e){if(!e)return;let t=e.trim().toLowerCase();if(!t)return;if(o(t))return t;if(t.startsWith(`[`)){let e=t.match(/^\[([^\]]+)\](?::(\d+))?$/);return!e||!u(e[2])?void 0:e[1]}let n=t.match(/^([^:]+)(?::(\d+))?$/);if(n&&u(n[2]))return n[1].replace(/\.$/,``)}function u(e){return e===void 0||Number(e)<=65535}function d(e,t){let n=l(e);return(n===`localhost`||c(n))&&c(t)}function f(e){let t=e.indexOf(`@`),n=t>=0?e.slice(0,t):e,r=n.indexOf(`:`);if(r>=0)return n.slice(0,r);let i=n.indexOf(`-`);return(i>=0?n.slice(0,i):n)||`misc`}function p(e,t){let n=new Map;if(!t.size)return n;for(let[r,i]of e)for(let e of i){if(!t.has(e))continue;let i=n.get(e);i||(i=[],n.set(e,i)),i.push(r)}for(let e of n.values())e.length>1&&e.sort();return n}function m(e){let t=new Set;for(let n of e.values())for(let e of n)t.add(e);return t}async function h(e,t,n={}){let r=await e.generate(t,{extendedInfo:!0,preflights:!1,safelist:n.safelist??!1,id:n.id}),i=n.moduleTokens?p(n.moduleTokens,r.matched):void 0,a=[];for(let[e,t]of r.matched){let n=``;for(let e of t.data){let t=e[2];t&&(n+=n?` ${t}`:t)}let r=i?.get(e)??[];a.push({token:e,css:n,count:i?r.length:1,category:f(e),modules:r})}a.sort((e,t)=>t.count-e.count||e.token.localeCompare(t.token));let o=r.layers.map(e=>({name:e,css:r.getLayer(e)??``}));return{css:r.css,layers:o,matched:a}}const g=`__teacss`,_=`__teacss_api`,v=e=>e.split(`?`)[0],y=e=>e.replace(/([?&])(?:t|v)=[^&]+$/,``).replace(/\?$/,``);function b(e){let t=new Map;for(let[n,r]of e)t.set(n,r.tokens);return t}const x=RegExp(`(//\\s*?${r}\\s*?|\\/\\*\\s*?${r}\\s*?\\*\\/|<!--\\s*?${r}\\s*?-->)[\\s\\S]*?(//\\s*?${n}\\s*?|\\/\\*\\s*?${n}\\s*?\\*\\/|<!--\\s*?${n}\\s*?-->)`,`g`);function S(e){return!e.includes(r)||!e.includes(n)?e:e.replace(x,``)}async function C(e){await e[Symbol.for(`@teacss/engine/materialize`)]?.();let t=e.config;return{presets:t.presets.map(e=>e.name).filter(e=>!!e),layers:Object.entries(t.layers).sort((e,t)=>e[1]-t[1]),rules:t.rules.length,shortcuts:Array.isArray(t.shortcuts)?t.shortcuts.length:Object.keys(t.shortcuts).length,themeKeys:Object.keys(t.theme)}}async function w(e,t,n){return{version:t.version,root:e.root,modules:[...n.keys()].sort(),configSources:e.getConfigFileList?.()??[],config:await C(t)}}const T=e=>t(Buffer.from(e)).length;function E(e,t){let n;return async(r,i,a)=>{let o=(e,t=200)=>{i.statusCode=t,i.setHeader(`Content-Type`,`application/json`),i.end(JSON.stringify(e))};if(!d(r.headers.host,r.socket?.remoteAddress))return o({error:`forbidden`},403);try{let i=new URL(r.url??`/`,`http://localhost`);await e.ready;let s=e.generator,{modules:c}=t;switch(i.pathname){case`/`:case``:return o(await w(e,s,c));case`/overview`:{let r=t.version();if(n?.version===r)return o(n.data);let i=b(c),a=m(i);for(let t of e.tokens)a.add(t);let l=await h(s,a,{moduleTokens:i}),u={...l,gzipSize:T(l.css)};return n={version:r,data:u},o(u)}case`/repl`:{let e=i.searchParams.get(`token`)??``;return e.length>5e4?o({error:`input too large`},413):o(await h(s,e,{safelist:i.searchParams.get(`safelist`)===`true`}))}case`/module`:{let e=i.searchParams.get(`id`)??``,t=c.get(e);if(!t)return o({error:`module not found`},404);let n=await h(s,t.tokens,{id:e,moduleTokens:b(c)});return o({...n,id:e,code:t.code,gzipSize:T(n.css)})}default:return a()}}catch(e){o({error:e instanceof Error?e.message:String(e)},500)}}}function D(){let t=new Map,n=new Map,r=new Map,a=0,o=()=>{a++},s={modules:t,version:()=>a},c,l,u,d;function f(e){let r=n.get(e);if(!r?.size){n.delete(e),t.delete(e);return}if(r.size===1){t.set(e,r.values().next().value);return}let i=new Set;for(let e of r.values())for(let t of e.tokens)i.add(t);let a=r.get(e)?.code??[...r.values()].map(e=>e.code).join(`
-`);t.set(e,{code:a,tokens:i})}function p(e,t){return n.get(e)?.delete(t)?(f(e),!0):!1}function m(e){let i=v(e),a=y(e);if(a!==i){r.delete(a),p(i,a)&&o();return}for(let e of r.keys())v(e)===i&&r.delete(e);let s=n.delete(i),c=t.delete(i);(s||c)&&o()}function h(){d?.(),d=void 0,u?.watcher.off(`unlink`,m),u=void 0}function b(){r.clear();let e=t.size>0||n.size>0;t.clear(),n.clear(),e&&o()}function x(){h(),l?.(),l=void 0,b(),c=void 0}return{name:`teacss:inspector`,apply:`serve`,configResolved(e){l?.(),l=void 0;let t=(e.plugins.find(e=>e.name===`teacss:api`)?.api)?.getContext?.();c!==t&&(h(),b()),c=t,c?l=c.onInvalidate(o):e.logger.warn(`[teacss:inspector] no pluginTeacss() plugin found — the inspector is disabled.`)},async transform(e,t){let i=c;if(!i)return null;let a=v(t),s=y(t),l={};if(r.set(s,l),!i.filter(e,t))return r.delete(s),p(a,s)&&o(),null;try{await i.ready;let u=await i.generator.applyExtractors(S(e),t,new Set);if(c!==i||r.get(s)!==l)return null;if(u.size){let t=n.get(a);t||n.set(a,t=new Map),t.set(s,{code:e,tokens:u}),f(a),o()}else p(a,s)&&o();return null}finally{r.get(s)===l&&r.delete(s)}},async configureServer(t){let n=c;if(!n||(await n.ready,c!==n||u===t))return;if(h(),u=t,t.watcher.on(`unlink`,m),t.httpServer){let e=()=>{u===t&&x()};t.httpServer.once(`close`,e),d=()=>t.httpServer?.off(`close`,e)}let r=e(new URL(`./client`,import.meta.url));t.middlewares.use(`/${g}`,i(r,{single:!0,dev:!0})),t.middlewares.use(`/${_}`,E(n,s)),t.config.logger.info(`\n  \x1b[32m➜\x1b[0m  \x1b[36mTeaCSS Inspector\x1b[0m: \x1b[2mhttp://localhost:${t.config.server.port??5173}/${g}/\x1b[0m\n`)},closeBundle(){x()},devtools:{setup(e){e.docks.register({id:`teacss`,title:`TeaCSS`,icon:`mdi:tea`,type:`iframe`,url:`/${g}/`})}}}}export{_ as API_BASE,g as CLIENT_BASE,f as categoryOf,E as createInspectorApi,h as generateDTO,D as pluginInspector};
+import { fileURLToPath } from "node:url";
+import { version } from "@teacss/engine";
+import sirv from "sirv";
+import { isLoopbackRequest } from "./access.js";
+/** A REPL body past this is refused before it is read into memory (the engine's own source bound is v02.2 §8's 16 MiB). */
+const MAX_BODY_BYTES = 1 << 20;
+const CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
+/** `GET /api/token/<token>`; the token is percent-encoded, so `rd:1/2` arrives as `rd%3A1%2F2`. */
+const TOKEN_ROUTE = "/api/token/";
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** `/api/suggest` answers at most this many candidates; `limit` can lower it. */
+const MAX_SUGGESTIONS = 100;
+/**
+ * v10.2 §3.6: `/api/project`, `/api/modules`, `/api/css`, `/api/stats` and `POST /api/repl` read `project` through napi;
+ * v10.3 §5 adds `/api/token/<token>` and `/api/suggest?q=`, and `/api/module?id=` generates one module's token list.
+ * Every other path is the static UI. Only loopback requests are answered (403 otherwise).
+ */
+export function createInspectorMiddleware(project) {
+    const ui = sirv(CLIENT_DIR, { single: true });
+    return (req, res, next) => {
+        const reply = ({ status, body }) => {
+            res.statusCode = status;
+            res.setHeader("Content-Type", "application/json; charset=utf-8");
+            res.end(JSON.stringify(body));
+        };
+        if (!isLoopbackRequest(req.headers.host, req.socket.remoteAddress)) {
+            reply({ status: 403, body: { error: "inspector is loopback-only" } });
+            return;
+        }
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (!url.pathname.startsWith("/api/")) {
+            ui(req, res, next);
+            return;
+        }
+        route(project, req, url)
+            .catch((error) => ({ status: error instanceof HttpError ? error.status : 500, body: { error: error instanceof Error ? error.message : String(error) } }))
+            .then(reply);
+    };
+}
+async function route(project, req, url) {
+    const { engine } = project;
+    const { pathname } = url;
+    if (req.method === "GET" && pathname.startsWith(TOKEN_ROUTE)) {
+        const token = decodeToken(pathname.slice(TOKEN_ROUTE.length));
+        const info = engine.tokenInfo(token);
+        return info ? { status: 200, body: info } : { status: 404, body: { error: `no utility matches ${JSON.stringify(token)}` } };
+    }
+    switch (`${req.method} ${pathname}`) {
+        case "GET /api/project": {
+            const body = { version: version(), root: project.root, ...project.info, config: engine.configView() };
+            return { status: 200, body };
+        }
+        case "GET /api/modules": {
+            const body = project.modules().map((id) => ({ id, tokens: engine.moduleTokens(id) ?? [] }));
+            return { status: 200, body };
+        }
+        case "GET /api/module": {
+            const tokens = engine.moduleTokens(url.searchParams.get("id") ?? "");
+            if (tokens === null)
+                throw new HttpError(404, "no such module");
+            return { status: 200, body: engine.generate({ kind: "tokens", tokens }, { css: true, extendedInfo: true, preflights: false }) };
+        }
+        case "GET /api/css":
+            return { status: 200, body: project.css({ extendedInfo: true }) };
+        case "GET /api/stats":
+            return { status: 200, body: engine.stats() };
+        case "GET /api/suggest": {
+            const q = url.searchParams.get("q");
+            if (q === null)
+                throw new HttpError(400, "query needs q=<input>");
+            return { status: 200, body: engine.suggest(q, { limit: parseLimit(url.searchParams.get("limit")) }) };
+        }
+        case "POST /api/repl": {
+            const { code, safelist = false } = parseRepl(await readBody(req));
+            return { status: 200, body: engine.generate({ kind: "code", code }, { css: true, extendedInfo: true, preflights: false, safelist }) };
+        }
+        default:
+            return { status: 404, body: { error: `no route ${req.method} ${pathname}` } };
+    }
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES)
+                reject(new HttpError(413, `body over ${MAX_BODY_BYTES} bytes`));
+            else
+                chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function parseRepl(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new HttpError(400, "body is not JSON");
+    }
+    const { code, safelist } = (typeof parsed === "object" && parsed !== null ? parsed : {});
+    if (typeof code !== "string" || (safelist !== undefined && typeof safelist !== "boolean"))
+        throw new HttpError(400, 'body must be { "code": string, "safelist"?: boolean }');
+    return { code, safelist };
+}
+function decodeToken(encoded) {
+    try {
+        return decodeURIComponent(encoded);
+    }
+    catch {
+        throw new HttpError(400, "token is not percent-encoded");
+    }
+}
+/** `limit` as a count in 0–MAX_SUGGESTIONS; absent means the maximum. */
+function parseLimit(raw) {
+    if (raw === null)
+        return MAX_SUGGESTIONS;
+    const limit = Number(raw);
+    if (!Number.isInteger(limit) || limit < 0)
+        throw new HttpError(400, "limit must be a non-negative integer");
+    return Math.min(limit, MAX_SUGGESTIONS);
+}
+//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+import type { LoadProjectFromRootResult, ResolvedConfigView } from "@teacss/engine";
+/** GET /api/project: the engine version, the shell's root, the latest `loadProjectFromRoot` result and `configView()`. */
+export interface ProjectResponse extends LoadProjectFromRootResult {
+    version: string;
+    root: string;
+    config: ResolvedConfigView;
+}
+/** GET /api/modules: one entry per module the shell registered, with the tokens the engine extracted from it. */
+export interface ModuleTokens {
+    id: string;
+    tokens: string[];
+}
+/** POST /api/repl body; the answer is `generate({ kind: "code", code })` without preflights. `safelist` defaults to false. */
+export interface ReplRequest {
+    code: string;
+    safelist?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,47 +1,60 @@
 {
   "name": "@teacss/inspector",
-  "version": "0.9.3",
-  "description": "The inspector UI for TeaCSS — browse generated CSS, modules, and a live REPL.",
-  "homepage": "https://css.teasim.com",
-  "funding": "https://github.com/sponsors/billgo",
+  "version": "0.10.2",
+  "description": "TeaCSS inspector: the dev-server page @teacss/vite mounts at /__teacss, reading the Rust engine (@teacss/engine)",
   "license": "MIT",
-  "author": "Billgo <hi@billgo.me>",
-  "sideEffects": false,
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teacss/teacss-rs.git",
+    "directory": "packages/inspector"
+  },
+  "homepage": "https://github.com/teacss/teacss-rs/tree/master/packages/inspector#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
+  "imports": {
+    "#src/*": "./dist/*"
+  },
   "files": [
-    "dist",
-    "README.md"
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/client",
+    "README.md",
+    "LICENSE"
   ],
-  "scripts": {
-    "build": "bunx rimraf dist && bunx tsdown --config tsdown.config.mts && bunx vite build",
-    "dev": "tsdown --watch",
-    "dev:client": "vite"
+  "sideEffects": false,
+  "engines": {
+    "node": ">=26"
   },
   "dependencies": {
-    "@teacss/core": "0.9.3",
-    "sirv": "^3.0.2"
+    "@teacss/engine": "0.10.2",
+    "sirv": "^3"
   },
   "devDependencies": {
-    "@teacss/preset-standard": "0.9.3",
+    "@types/node": "^22.20.5",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.7",
-    "@vitejs/devtools-kit": "^0.7.2",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "vite": "^8.2.2"
-  },
-  "peerDependencies": {
-    "vite": ">=5.0.0"
+    "typescript": "^5.9.3",
+    "vite": "^7.3.7"
   },
-  "engines": {
-    "node": ">=22.12.0"
+  "scripts": {
+    "build:client": "vite build",
+    "build:ts": "node -e \"for (const d of ['build','dist']) require('fs').rmSync(d,{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+    "build": "npm run build:ts && npm run build:client",
+    "check:types": "tsc -p tsconfig.json && tsc -p tsconfig.test.json --noEmit && tsc -p client/tsconfig.json",
+    "test": "npm run build && node --test \"build/tests/**/*.test.js\""
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   }
 }