@jesscss/plugin-js 2.0.0-alpha.1 → 2.0.0-alpha.11

package/README.md

@@ -1,6 +1,50 @@
 # @jesscss/plugin-js
 
-Jess plugin that enables JavaScript/TypeScript module imports.
+**Import bridge for JavaScript/TypeScript modules in stylesheets — a seed of the
+JavaScript-execution / CSS-in-JS story.**
 
-This package checks for a usable Deno runtime before executing non-`@jesscss/fns`
-modules. It is intended to be auto-loaded by `jess` when installed.
+This plugin lets a stylesheet pull in JavaScript/TypeScript modules
+(`.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`) — the mechanism behind `@use` /
+`@-from` script imports and legacy Less `@plugin` loading. When installed, it is
+auto-loaded by `jess`.
+
+## Sandboxed execution
+
+`plugin-js` does **not** run untrusted module code in your Node process. Before
+executing anything, it checks for a usable **Deno** runtime (`deno --version`)
+and runs the module in a Deno subprocess behind a permission broker:
+
+- **read** is limited to `node_modules` (and an optional `jsReadRoot`),
+- **net** is denied unless you opt in (`allowHttp`, optionally scoped to
+  `allowNetHosts`),
+- **env / write / run / ffi / sys** are denied outright.
+
+Values cross the boundary through a small typed bridge (dimensions, colors,
+quoted strings, lists, detached rules, …). Built-in `@jesscss/fns` modules are
+trusted and imported directly, without the worker. If no Deno binary is found,
+the plugin fails with a clear message instead of falling back to unsandboxed
+execution.
+
+## Why it exists — the convergence angle
+
+One of the four tools [Jess](https://github.com/jesscss/jess) aims to converge is
+**CSS-in-JS**: running real JavaScript inside stylesheets so styles can be
+dynamic without leaving CSS files. This plugin — together with
+[`@jesscss/plugin-node-modules`](../jess-plugin-node-modules), which resolves the
+packages — is a seed of that story.
+
+That convergence is **roadmap — being proven through the alpha, not claimed as
+done.** Legacy Less `@plugin` is supported for compatibility but deprecated in
+favor of `@-from` / `@-use`.
+
+## Status
+
+**Alpha.** Part of Jess. Requires a Deno runtime for script execution. The
+programmatic plugin/compiler API is **not yet stabilized** — the `jess` CLI is
+the documented public surface for the alpha. Watch the
+[docs site](https://jesscss.github.io/) for the API once it settles.
+
+- Project overview & positioning: <https://github.com/jesscss/jess#readme>
+- Docs: <https://jesscss.github.io/> (currently pre-alpha content)
+- Issues: <https://github.com/jesscss/jess/issues>
+- License: MIT

package/lib/bridge.d.ts

@@ -0,0 +1,46 @@
+export type JsBridgeDeclaration = {
+    name: string;
+    value: JsBridgeValue;
+};
+export type JsBridgeValue = {
+    __jessBridge: true;
+    kind: 'scalar';
+    value: string | number | boolean;
+} | {
+    __jessBridge: true;
+    kind: 'dimension';
+    value: number;
+    unit?: string;
+} | {
+    __jessBridge: true;
+    kind: 'color';
+    rgb: [number, number, number];
+    alpha?: number;
+} | {
+    __jessBridge: true;
+    kind: 'quoted';
+    value: string;
+    quote?: '"' | '\'';
+    escaped?: boolean;
+} | {
+    __jessBridge: true;
+    kind: 'anonymous';
+    value: string;
+} | {
+    __jessBridge: true;
+    kind: 'list';
+    items: JsBridgeValue[];
+    separator: ',' | '/' | ';';
+} | {
+    __jessBridge: true;
+    kind: 'expression';
+    items: JsBridgeValue[];
+} | {
+    __jessBridge: true;
+    kind: 'mixin';
+    rules: JsBridgeDeclaration[];
+};
+export declare function encodeBridgeValue(value: unknown): unknown;
+export declare function decodeBridgeValue(value: unknown): unknown;
+export declare function encodeBridgeArgs(args: readonly unknown[]): unknown[];
+//# sourceMappingURL=bridge.d.ts.map

package/lib/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAEzE,MAAM,MAAM,aAAa,GACrB;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;CAAE,GACxE;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACpF;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5F;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAC;IAAC,SAAS,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;CAAE,GACxF;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GAClE;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAiGxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA8BzD;AAkDD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE,CAEpE"}