@oxprotocol/cli 0.1.0

package/dist/lib/vsx-install.js

@@ -0,0 +1,74 @@
+/**
+ * VSX install adapter — handles `oxp install @publisher/slug` for entries
+ * that are mirrored from Open VSX rather than published natively to OXP.
+ *
+ * Strategy:
+ *   1. Caller pre-fetched `/api/v1/extensions/<publisher>/<slug>` and
+ *      saw a `vsx` block in the response → call `installVsx()`.
+ *   2. We detect the user's VS Code-family IDEs (already done by the
+ *      install command) and run `<cli> --install-extension <ns>.<name>`
+ *      against each one. The IDE's own install path handles VSIX fetch,
+ *      signature checks (or lack thereof), and registration.
+ *   3. We DO NOT touch the OXP shared host-store — VSX extensions are
+ *      not OXP wasm components and have no oxp.json runtime contract.
+ *
+ * This keeps the CLI honest: VSX entries are explicitly delegated to
+ * the IDE, and we surface that in CLI output so the user knows what
+ * happened.
+ */
+import { spawnSync } from "node:child_process";
+/**
+ * Run `<cliPath> --install-extension <namespace>.<name>` against every
+ * detected vscode-family host. JetBrains/Zed/Piye are reported as
+ * skipped since they have no compatible install command for VSIX.
+ */
+export function installVsx(target, hosts) {
+    const ext = `${target.namespace}.${target.name}`;
+    const out = [];
+    for (const host of hosts) {
+        if (host.family !== "vscode") {
+            out.push({
+                host,
+                status: "skipped",
+                reason: `family ${host.family} can't install VSIX via --install-extension`,
+            });
+            continue;
+        }
+        if (!host.cliPath) {
+            out.push({
+                host,
+                status: "skipped",
+                reason: "no CLI launcher on PATH",
+            });
+            continue;
+        }
+        const res = spawnSync(host.cliPath, ["--install-extension", ext], {
+            encoding: "utf8",
+            // Cap runtime so a hung IDE process can't block the CLI forever.
+            timeout: 60_000,
+        });
+        const tail = (res.stdout || "") + (res.stderr || "");
+        const trimmed = tail.length > 400 ? tail.slice(-400) : tail;
+        if (res.error) {
+            out.push({
+                host,
+                status: "failed",
+                reason: res.error.message,
+                output: trimmed,
+            });
+            continue;
+        }
+        if (res.status !== 0) {
+            out.push({
+                host,
+                status: "failed",
+                reason: `${host.cliPath} exited with code ${res.status}`,
+                output: trimmed,
+            });
+            continue;
+        }
+        out.push({ host, status: "ok", output: trimmed });
+    }
+    return out;
+}
+//# sourceMappingURL=vsx-install.js.map

package/dist/lib/vsx-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vsx-install.js","sourceRoot":"","sources":["../../src/lib/vsx-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAqB/C;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,MAAwB,EACxB,KAAqB;IAErB,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;IACjD,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7B,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI;gBACJ,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,UAAU,IAAI,CAAC,MAAM,6CAA6C;aAC3E,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI;gBACJ,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,yBAAyB;aAClC,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,qBAAqB,EAAE,GAAG,CAAC,EAAE;YAChE,QAAQ,EAAE,MAAM;YAChB,iEAAiE;YACjE,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5D,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI;gBACJ,MAAM,EAAE,QAAQ;gBAChB,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO;gBACzB,MAAM,EAAE,OAAO;aAChB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrB,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI;gBACJ,MAAM,EAAE,QAAQ;gBAChB,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,qBAAqB,GAAG,CAAC,MAAM,EAAE;gBACxD,MAAM,EAAE,OAAO;aAChB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/util.d.ts

@@ -0,0 +1,10 @@
+/** Shared helpers for OXP CLI commands. */
+export declare function oxpHome(): string;
+export declare function registryUrl(): string;
+export declare function readCredentials(): Promise<string | null>;
+export declare function writeCredentials(token: string): Promise<void>;
+/** Find the project root (first ancestor containing oxp.json). */
+export declare function findProjectRoot(start: string): Promise<string | null>;
+export declare function info(msg: string): void;
+export declare function fail(msg: string): never;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAM3C,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAKD,wBAAgB,WAAW,IAAI,MAAM,CAgBpC;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO9D;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnE;AAED,kEAAkE;AAClE,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAa3E;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAGvC"}

package/dist/util.js

@@ -0,0 +1,64 @@
+/** Shared helpers for OXP CLI commands. */
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+export function oxpHome() {
+    return process.env.OXP_HOME ?? join(homedir(), ".oxp");
+}
+const DEFAULT_REGISTRY = "http://localhost:3000";
+let warnedDefaultRegistry = false;
+export function registryUrl() {
+    const fromEnv = process.env.OXP_REGISTRY;
+    if (fromEnv && fromEnv.trim().length > 0) {
+        return fromEnv.replace(/\/+$/, "");
+    }
+    // Localhost default is convenient for self-host / dev, but if you're trying
+    // to publish or install against the public registry it's almost always a
+    // mistake. Warn once per process so it's visible without becoming spammy.
+    if (!warnedDefaultRegistry) {
+        warnedDefaultRegistry = true;
+        process.stderr.write(`[oxp] OXP_REGISTRY not set — defaulting to ${DEFAULT_REGISTRY}. ` +
+            `Set OXP_REGISTRY=https://… to target a different host.\n`);
+    }
+    return DEFAULT_REGISTRY;
+}
+export async function readCredentials() {
+    try {
+        const buf = await fs.readFile(join(oxpHome(), "credentials"), "utf8");
+        return buf.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCredentials(token) {
+    const dir = oxpHome();
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, "credentials");
+    await fs.writeFile(path, token + "\n", { mode: 0o600 });
+}
+/** Find the project root (first ancestor containing oxp.json). */
+export async function findProjectRoot(start) {
+    let cur = resolve(start);
+    while (true) {
+        try {
+            await fs.access(join(cur, "oxp.json"));
+            return cur;
+        }
+        catch {
+            // continue
+        }
+        const parent = dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+export function info(msg) {
+    process.stdout.write(msg + "\n");
+}
+export function fail(msg) {
+    process.stderr.write(`oxp: ${msg}\n`);
+    process.exit(1);
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@oxprotocol/cli",
+  "version": "0.1.0",
+  "description": "Command-line tool for the Open eXtensions Protocol.",
+  "type": "module",
+  "bin": {
+    "oxp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./create": {
+      "types": "./dist/commands/create.d.ts",
+      "default": "./dist/commands/create.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "ws": "^8.18.0",
+    "@oxprotocol/bundle": "0.1.0",
+    "@oxprotocol/host-core": "0.1.0",
+    "@oxprotocol/wit": "0.1.0",
+    "@oxprotocol/types": "0.1.0",
+    "@oxprotocol/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/ws": "^8.5.13",
+    "tsx": "^4.20.6",
+    "typescript": "5.9.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/templates/hello-code/README.md

@@ -0,0 +1,39 @@
+# __DISPLAY_NAME__
+
+OXP code extension scaffolded from the `hello-code` template.
+
+## Develop
+
+```sh
+pnpm install
+pnpm dev          # start the dev loop (watch + hot-reload)
+```
+
+## Publish
+
+```sh
+pnpm pack         # build → dist/__SLUG__-0.0.1.oxp
+oxp publish       # upload to the registry
+```
+
+## Capabilities
+
+Declare what your extension needs in `oxp.json` → `permissions`:
+
+- `read-clipboard`
+- `write-clipboard`
+- `storage:local`
+- `network:<domain>` (e.g. `network:api.example.com`, or `network:*`)
+
+Use them via the `host` API:
+
+```ts
+import { defineExtension, clipboard, net } from "@oxprotocol/sdk";
+
+export default defineExtension({
+  async activate(host) {
+    const cb = clipboard(host);
+    await cb.write("hello");
+  },
+});
+```

package/templates/hello-code/oxp.json

@@ -0,0 +1,14 @@
+{
+  "specVersion": "1",
+  "id": "@__PUBLISHER__/__SLUG__",
+  "publisher": "__PUBLISHER__",
+  "version": "0.0.1",
+  "displayName": "__DISPLAY_NAME__",
+  "description": "An OXP code extension built with @oxprotocol/sdk.",
+  "license": "MIT",
+  "categories": ["other"],
+  "engines": { "oxp": "^1.0.0" },
+  "main": { "entry": "dist/extension.js" },
+  "ui": { "preferredSurface": "panel" },
+  "permissions": []
+}

package/templates/hello-code/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@__PUBLISHER__/__SLUG__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "oxp dev",
+    "pack": "pnpm build && oxp pack",
+    "publish:oxp": "pnpm pack && oxp publish"
+  },
+  "dependencies": {
+    "@oxprotocol/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/templates/hello-code/src/extension.ts

@@ -0,0 +1,17 @@
+import { defineExtension } from "@oxprotocol/sdk";
+
+export default defineExtension({
+  async activate(host) {
+    host.log("info", "hello from @__PUBLISHER__/__SLUG__");
+    host.renderHtml(`
+      <div style="font-family:system-ui;padding:2rem;color:#f8fafc;background:#060a13;min-height:100vh;display:grid;place-items:center">
+        <div style="border:1px solid rgba(125,211,252,.3);padding:2rem;border-radius:8px;text-align:center">
+          <h1 style="margin:0 0 .5rem;font-size:1.5rem">__DISPLAY_NAME__</h1>
+          <p style="margin:0;opacity:.6;font-family:ui-monospace,monospace;font-size:.75rem">
+            @__PUBLISHER__/__SLUG__
+          </p>
+        </div>
+      </div>
+    `);
+  },
+});

package/templates/hello-code/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ES2022",
+        "moduleResolution": "bundler",
+        "lib": [
+            "ES2022",
+            "DOM",
+            "WebWorker"
+        ],
+        "strict": true,
+        "outDir": "dist",
+        "rootDir": "src",
+        "declaration": false,
+        "skipLibCheck": true
+    },
+    "include": [
+        "src"
+    ]
+}

package/templates/hello-html/README.md

@@ -0,0 +1,18 @@
+# __DISPLAY_NAME__
+
+A minimal OXP extension scaffolded by `oxp create`.
+
+## Build
+
+```sh
+oxp pack
+```
+
+Writes `dist/__SLUG__-<version>.oxp` and `dist/__SLUG__-<version>.sig.json`.
+
+## Publish
+
+```sh
+oxp login                     # paste an API token from the registry
+oxp publish dist/__SLUG__-*.oxp
+```

package/templates/hello-html/oxp.json

@@ -0,0 +1,14 @@
+{
+  "specVersion": "1",
+  "id": "@__PUBLISHER__/__SLUG__",
+  "publisher": "__PUBLISHER__",
+  "version": "0.0.1",
+  "displayName": "__DISPLAY_NAME__",
+  "description": "Hello, OXP world.",
+  "license": "MIT",
+  "categories": ["other"],
+  "engines": { "oxp": "^1.0.0" },
+  "main": { "ui": "ui/index.html" },
+  "ui": { "components": "oxp-ui-only", "preferredSurface": "panel" },
+  "permissions": []
+}

package/templates/hello-html/ui/index.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>__DISPLAY_NAME__</title>
+    <style>
+      :root {
+        color-scheme: dark light;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        font-family: -apple-system, system-ui, sans-serif;
+        background: #060a13;
+        color: #f8fafc;
+      }
+      .card {
+        border: 1px solid rgba(125, 211, 252, 0.3);
+        padding: 2rem 2.5rem;
+        border-radius: 8px;
+        text-align: center;
+      }
+      h1 {
+        margin: 0 0 0.5rem;
+        font-size: 1.75rem;
+      }
+      p {
+        margin: 0;
+        opacity: 0.6;
+        font-family: ui-monospace, monospace;
+        font-size: 0.75rem;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>Hello, OXP world.</h1>
+      <p>@__PUBLISHER__/__SLUG__</p>
+    </div>
+  </body>
+</html>

package/templates/hello-rust/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "__SLUG_UNDERSCORED__"
+version = "0.0.1"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wit-bindgen = "0.36"
+
+[profile.release]
+# These flags shrink the resulting .wasm dramatically. Hello-world
+# components built with this profile land under 50 KB.
+opt-level = "s"
+lto = true
+strip = true
+codegen-units = 1

package/templates/hello-rust/README.md

@@ -0,0 +1,50 @@
+# __DISPLAY_NAME__
+
+A `component-v1` OXP extension written in Rust, targeting the
+[WASI Preview 2](https://github.com/WebAssembly/WASI) component model
+and the canonical `oxp:extension@0.1.0` world.
+
+## Prerequisites
+
+```sh
+rustup target add wasm32-wasip2
+```
+
+## Build & pack
+
+```sh
+oxp pack
+# → runs `scripts.build` from oxp.json (cargo build + copy)
+# → writes dist/__SLUG__-0.0.1.oxp
+```
+
+If you want to skip the build hook (e.g. you've built manually):
+
+```sh
+oxp pack --no-build
+```
+
+## What does it do?
+
+The `activate` lifecycle export logs a single line via the always-on
+`oxp:host/log` interface. `deactivate` logs `"goodbye"`. That's the
+whole extension — it's deliberately minimal so you can verify the
+toolchain end-to-end before adding logic.
+
+## Layout
+
+```
+oxp.json       OXP manifest (component-v1, pins oxp:extension@0.1.0)
+Cargo.toml     Rust crate definition (cdylib)
+src/lib.rs     Component implementation (lifecycle + ui-handler + command-handler)
+wit/           WIT contract — extension.wit + deps/oxp-host/oxp-host.wit
+build/         Built .wasm artefact — packed into the bundle
+dist/          Output of `oxp pack` (.oxp + signature); gitignored
+```
+
+The `wit/` directory is shipped inline so the project builds without
+any monorepo dependency. If the upstream `oxp:extension` world ever
+changes you'll need to refresh the files and update `oxp.json#wit.sha256`
+to match — `oxp create --template hello-rust` always emits the current
+hash, so the easy fix is to scaffold a fresh project and copy the new
+WIT files + sha across.

package/templates/hello-rust/oxp.json

@@ -0,0 +1,22 @@
+{
+  "specVersion": "1",
+  "id": "@__PUBLISHER__/__SLUG__",
+  "publisher": "__PUBLISHER__",
+  "version": "0.0.1",
+  "displayName": "__DISPLAY_NAME__",
+  "description": "OXP component-v1 extension written in Rust.",
+  "license": "MIT",
+  "categories": ["other"],
+  "engines": { "oxp": "^1.0.0" },
+  "kind": "component-v1",
+  "main": { "wasm": "build/__SLUG_UNDERSCORED__.wasm" },
+  "scripts": {
+    "build": "cargo build --release --target wasm32-wasip2 && mkdir -p build && cp target/wasm32-wasip2/release/__SLUG_UNDERSCORED__.wasm build/"
+  },
+  "permissions": [],
+  "wit": {
+    "package": "oxp:extension",
+    "version": "0.1.0",
+    "sha256": "__WIT_SHA__"
+  }
+}

package/templates/hello-rust/src/lib.rs

@@ -0,0 +1,111 @@
+// Hello-world OXP extension component, written in Rust.
+//
+// Exercises:
+//   * activate / deactivate lifecycle exports
+//   * a single always-on host import: oxp:host/log
+//
+// To build:
+//   rustup target add wasm32-wasip2
+//   cargo build --release --target wasm32-wasip2
+//   mkdir -p build && cp target/wasm32-wasip2/release/__SLUG_UNDERSCORED__.wasm build/
+//   oxp pack
+
+wit_bindgen::generate!({
+    world: "extension",
+    path: "wit",
+    generate_all,
+});
+
+use exports::oxp::extension::command_handler::Guest as CommandHandlerGuest;
+use exports::oxp::extension::lifecycle::{ActivateCtx, Guest as LifecycleGuest};
+use exports::oxp::extension::ui_handler::{EventError, Guest as UiHandlerGuest};
+use oxp::host::log::{log, Level};
+
+struct Component;
+
+impl LifecycleGuest for Component {
+    fn activate(ctx: ActivateCtx) -> Result<(), String> {
+        log(
+            Level::Info,
+            &format!(
+                "hello from {} v{} on host {} ({})",
+                ctx.extension_id, ctx.version, ctx.host, ctx.host_version
+            ),
+        );
+        Ok(())
+    }
+
+    fn deactivate() -> Result<(), String> {
+        log(Level::Info, "goodbye");
+        Ok(())
+    }
+}
+
+impl UiHandlerGuest for Component {
+    fn on_event(_event: Vec<u8>) -> Result<(), EventError> {
+        Ok(())
+    }
+}
+
+impl CommandHandlerGuest for Component {
+    fn on_command(id: String, args_json: String) -> Result<String, String> {
+        match id.as_str() {
+            // Replace this with your own command. The result must be valid JSON.
+            "hello.greet" => {
+                let name = parse_json_string_field(&args_json, "name")
+                    .unwrap_or_else(|| "world".to_string());
+                Ok(format!("\"hello, {}!\"", json_escape(&name)))
+            }
+            other => Ok(format!("\"unhandled:{}\"", other)),
+        }
+    }
+}
+
+// Tiny zero-dependency JSON helpers so the template doesn't pull in serde
+// just for one example. Replace with serde_json once your extension grows.
+fn parse_json_string_field(json: &str, field: &str) -> Option<String> {
+    let needle = format!("\"{field}\"");
+    let start = json.find(&needle)? + needle.len();
+    let rest = &json[start..];
+    let colon = rest.find(':')? + 1;
+    let after_colon = &rest[colon..];
+    let q = after_colon.find('"')? + 1;
+    let body = &after_colon[q..];
+    let mut out = String::new();
+    let mut chars = body.chars();
+    while let Some(c) = chars.next() {
+        if c == '\\' {
+            match chars.next()? {
+                'n' => out.push('\n'),
+                't' => out.push('\t'),
+                'r' => out.push('\r'),
+                '"' => out.push('"'),
+                '\\' => out.push('\\'),
+                other => out.push(other),
+            }
+        } else if c == '"' {
+            return Some(out);
+        } else {
+            out.push(c);
+        }
+    }
+    None
+}
+
+fn json_escape(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    for c in s.chars() {
+        match c {
+            '"' => out.push_str("\\\""),
+            '\\' => out.push_str("\\\\"),
+            '\n' => out.push_str("\\n"),
+            '\r' => out.push_str("\\r"),
+            '\t' => out.push_str("\\t"),
+            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
+            c => out.push(c),
+        }
+    }
+    out
+}
+
+export!(Component);