@ttsc/playground 0.14.0-dev.20260528.1 → 0.14.0-dev.20260529.1

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 (2) hide show
  1. package/README.md +29 -68
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,23 +1,12 @@
1
1
  # @ttsc/playground
2
2
 
3
- > **API stability: experimental until v1.0.** Public signatures (the
4
- > `createWorkerCompiler` options, `ICompilerService` contract, React
5
- > component props) may change between minor releases. Pin exact versions in
6
- > production playgrounds.
3
+ > **API stability: experimental until v1.0.** Public signatures (the `createWorkerCompiler` options, `ICompilerService` contract, React component props) may change between minor releases. Pin exact versions in production playgrounds.
7
4
 
8
- Reusable Web Worker + React scaffolding for in-browser
9
- [`ttsc`](https://ttsc.dev) playgrounds. Built on top of
10
- [`@ttsc/wasm`](https://github.com/samchon/ttsc/tree/master/packages/wasm).
5
+ Reusable Web Worker + React scaffolding for in-browser [`ttsc`](https://ttsc.dev) playgrounds. Built on top of [`@ttsc/wasm`](https://github.com/samchon/ttsc/tree/master/packages/wasm).
11
6
 
12
- The package handles the parts every browser playground needs — worker boot,
13
- MemFS layout, race-guarded compile / lint / bundle calls, on-the-fly npm
14
- dependency installer, typia source-pack mounting, console-capturing execute
15
- sandbox — and ships a Tailwind-styled React shell that wires them all up.
16
- Sites supply the wasm URL, a default script, and (optionally) examples,
17
- brand slot, and an execute callback.
7
+ The package handles the parts every browser playground needs — worker boot, MemFS layout, race-guarded compile / lint / bundle calls, on-the-fly npm dependency installer, typia source-pack mounting, console-capturing execute sandbox — and ships a Tailwind-styled React shell that wires them all up. Sites supply the wasm URL, a default script, and (optionally) examples, brand slot, and an execute callback.
18
8
 
19
- The ttsc website (`ttsc.dev`) and the typia website (`typia.io`) are the two
20
- reference consumers.
9
+ The ttsc website (`ttsc.dev`) and the typia website (`typia.io`) are the two reference consumers.
21
10
 
22
11
  ## Install
23
12
 
@@ -26,22 +15,20 @@ npm install @ttsc/playground @ttsc/wasm \
26
15
  @monaco-editor/react monaco-editor react react-dom tgrid tailwindcss
27
16
  ```
28
17
 
29
- `@monaco-editor/react`, `monaco-editor`, `react`, `react-dom`, `tgrid`, and
30
- `@ttsc/wasm` are **peer dependencies**. `lz-string` is bundled.
18
+ `@monaco-editor/react`, `monaco-editor`, `react`, `react-dom`, `tgrid`, and `@ttsc/wasm` are **peer dependencies**. `lz-string` is bundled.
31
19
 
32
- The React components use Tailwind 4 utility classes — see
33
- [Tailwind setup](#tailwind-setup) below.
20
+ The React components use Tailwind 4 utility classes — see [Tailwind setup](#tailwind-setup) below.
34
21
 
35
22
  ## What you get
36
23
 
37
- | Layer | Exports |
38
- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
39
- | **Worker core** | `createWorkerCompiler`, `buildTsconfigJSON`, `installDependenciesIntoMemFS`, `mapDiagnostic`, `pickEmittedJS`, `DEFAULT_*` constants |
40
- | **Typia integration** | `createTypiaSourcePackMount`, `installTypiaSourcePack`, `loadTypiaSourcePack` |
41
- | **Npm installer** | `installPlaygroundDependencies`, `collectExternalPackageNames`, `packageNameFromSpecifier`, `BUILT_IN_PLAYGROUND_PACKAGES` |
42
- | **Execute sandbox** | `createSandboxRequire`, `loadTypiaRuntimePack` |
43
- | **React UI** | `PlaygroundShell`, `SourceEditor`, `ResultViewer`, `ConsoleViewer`, `OptionsPanel`, `DiagnosticsPanel`, `DependencyProgressModal`, `ExamplePicker`, `LintPane`, `createCompilerClient`, `DEFAULT_OPTION_TOGGLES` |
44
- | **Types** | Everything under `./src/structures/` |
24
+ | Layer | Exports |
25
+ | --- | --- |
26
+ | **Worker core** | `createWorkerCompiler`, `buildTsconfigJSON`, `installDependenciesIntoMemFS`, `mapDiagnostic`, `pickEmittedJS`, `DEFAULT_*` constants |
27
+ | **Typia integration** | `createTypiaSourcePackMount`, `installTypiaSourcePack`, `loadTypiaSourcePack` |
28
+ | **Npm installer** | `installPlaygroundDependencies`, `collectExternalPackageNames`, `packageNameFromSpecifier`, `BUILT_IN_PLAYGROUND_PACKAGES` |
29
+ | **Execute sandbox** | `createSandboxRequire`, `loadTypiaRuntimePack` |
30
+ | **React UI** | `PlaygroundShell`, `SourceEditor`, `ResultViewer`, `ConsoleViewer`, `OptionsPanel`, `DiagnosticsPanel`, `DependencyProgressModal`, `ExamplePicker`, `LintPane`, `createCompilerClient`, `DEFAULT_OPTION_TOGGLES` |
31
+ | **Types** | Everything under `./src/structures/` |
45
32
 
46
33
  ## Architecture
47
34
 
@@ -69,8 +56,7 @@ The React components use Tailwind 4 utility classes — see
69
56
 
70
57
  ## Worker entry (site-side)
71
58
 
72
- The worker entry is two lines. Wire the wasm URL the site ships and the
73
- `apiName` you used in `host.Expose` when you built the wasm.
59
+ The worker entry is two lines. Wire the wasm URL the site ships and the `apiName` you used in `host.Expose` when you built the wasm.
74
60
 
75
61
  ```ts
76
62
  // site/src/compiler/index.ts (rspack target: "webworker")
@@ -86,8 +72,7 @@ const service = createWorkerCompiler({
86
72
  await new WorkerServer().open(service);
87
73
  ```
88
74
 
89
- Bundle this file with rspack/webpack/vite as a webworker target and serve
90
- the output (e.g. at `/compiler/index.js`).
75
+ Bundle this file with rspack/webpack/vite as a webworker target and serve the output (e.g. at `/compiler/index.js`).
91
76
 
92
77
  ## UI shell (site-side)
93
78
 
@@ -115,8 +100,7 @@ export default function SitePlayground() {
115
100
 
116
101
  ## Typia integration (optional)
117
102
 
118
- When the wasm bundles the typia transform plugin, mount typia's source tree
119
- into the MemFS so `import typia from "typia"` resolves:
103
+ When the wasm bundles the typia transform plugin, mount typia's source tree into the MemFS so `import typia from "typia"` resolves:
120
104
 
121
105
  ```ts
122
106
  import {
@@ -137,17 +121,11 @@ const service = createWorkerCompiler({
137
121
  });
138
122
  ```
139
123
 
140
- The typia pack itself is built by the site (typically with a
141
- `pack-typia-sources.cjs`-style script that bundles `typia/`, `@typia/utils`,
142
- and `@typia/interface` into a flat JSON map). See the ttsc website's
143
- [`build/pack-typia-sources.cjs`](https://github.com/samchon/ttsc/blob/master/website/build/pack-typia-sources.cjs)
144
- for the reference implementation.
124
+ The typia pack itself is built by the site (typically with a `pack-typia-sources.cjs`-style script that bundles `typia/`, `@typia/utils`, and `@typia/interface` into a flat JSON map). See the ttsc website's [`build/pack-typia-sources.cjs`](https://github.com/samchon/ttsc/blob/master/website/build/pack-typia-sources.cjs) for the reference implementation.
145
125
 
146
126
  ## Runtime npm dependency installer
147
127
 
148
- When the user types `import {v4} from "uuid"`, the shell auto-fetches `uuid`
149
- (and its transitive deps) from the npm registry, unpacks the tgz in the
150
- browser, and mounts the files into the wasm MemFS — no proxy server needed.
128
+ When the user types `import {v4} from "uuid"`, the shell auto-fetches `uuid` (and its transitive deps) from the npm registry, unpacks the tgz in the browser, and mounts the files into the wasm MemFS — no proxy server needed.
151
129
 
152
130
  ```ts
153
131
  import {
@@ -162,13 +140,11 @@ const installed = await installPlaygroundDependencies(names, {
162
140
  // mount installed.compilerFiles into the wasm MemFS via service.installDependencies
163
141
  ```
164
142
 
165
- `PlaygroundShell` wires this automatically on every keystroke, debounced 900
166
- ms, with an abort signal on source change.
143
+ `PlaygroundShell` wires this automatically on every keystroke, debounced 900 ms, with an abort signal on source change.
167
144
 
168
145
  ## Tailwind setup
169
146
 
170
- The bundled React components use Tailwind 4 utility classes. The host site
171
- must load Tailwind for them to render correctly.
147
+ The bundled React components use Tailwind 4 utility classes. The host site must load Tailwind for them to render correctly.
172
148
 
173
149
  `postcss.config.mjs`:
174
150
 
@@ -192,39 +168,24 @@ export default config;
192
168
 
193
169
  Then `import "./global.css"` from the root layout.
194
170
 
195
- **`@ttsc/playground` must be a direct dependency** of the consuming
196
- package. Tailwind only scans paths the consumer points at — a
197
- transitively-installed copy (where @ttsc/playground is a dep of another
198
- package) lives under a different node_modules layout and the glob above
199
- won't find it without explicit re-targeting.
171
+ **`@ttsc/playground` must be a direct dependency** of the consuming package. Tailwind only scans paths the consumer points at — a transitively-installed copy (where @ttsc/playground is a dep of another package) lives under a different node_modules layout and the glob above won't find it without explicit re-targeting.
200
172
 
201
173
  ## Booting a custom wasm
202
174
 
203
175
  `createWorkerCompiler` is plugin-agnostic. To register a custom plugin set:
204
176
 
205
- 1. Write a Go `main_wasm.go` that calls `host.Expose("myApi", host.Config{
206
- Plugins: [...] })`. See [`@ttsc/wasm`](https://github.com/samchon/ttsc/tree/master/packages/wasm)
207
- for the host helper and the plugin contract.
177
+ 1. Write a Go `main_wasm.go` that calls `host.Expose("myApi", host.Config{ Plugins: [...] })`. See [`@ttsc/wasm`](https://github.com/samchon/ttsc/tree/master/packages/wasm) for the host helper and the plugin contract.
208
178
  2. Build the wasm with `GOOS=js GOARCH=wasm go build`.
209
- 3. Ship the wasm at any URL and pass it to `createWorkerCompiler({wasmUrl,
210
- apiName})`.
179
+ 3. Ship the wasm at any URL and pass it to `createWorkerCompiler({wasmUrl, apiName})`.
211
180
 
212
- If the wasm registers plugins other than typia / `@ttsc/lint`, pass
213
- `typiaPlugin: false` / `lintPlugin: false` to skip those default dispatchers
214
- and use your own toggles via `optionToggles` + a custom worker wrapper.
181
+ If the wasm registers plugins other than typia / `@ttsc/lint`, pass `typiaPlugin: false` / `lintPlugin: false` to skip those default dispatchers and use your own toggles via `optionToggles` + a custom worker wrapper.
215
182
 
216
183
  ## Conventions
217
184
 
218
- - **One type per file.** Public interfaces / types each live under
219
- `src/structures/` in a file named after the type. The barrel
220
- `structures/index.ts` re-exports everything.
221
- - **One public function per file.** Internal helpers may be grouped in
222
- `compiler/internal/` or `npm/internal/`.
223
- - **No sub-path exports.** Every public symbol is importable from the
224
- package root. Add a sub-path later only when a real consumer needs to
225
- avoid pulling React into a Node-only context.
185
+ - **One type per file.** Public interfaces / types each live under `src/structures/` in a file named after the type. The barrel `structures/index.ts` re-exports everything.
186
+ - **One public function per file.** Internal helpers may be grouped in `compiler/internal/` or `npm/internal/`.
187
+ - **No sub-path exports.** Every public symbol is importable from the package root. Add a sub-path later only when a real consumer needs to avoid pulling React into a Node-only context.
226
188
 
227
189
  ## Documents
228
190
 
229
- See the [`@ttsc/playground` guide](https://ttsc.dev/docs/playground) for the
230
- site-walkthrough version of this README.
191
+ See the [`@ttsc/playground` guide](https://ttsc.dev/docs/playground) for the site-walkthrough version of this README.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ttsc/playground",
3
- "version": "0.14.0-dev.20260528.1",
3
+ "version": "0.14.0-dev.20260529.1",
4
4
  "description": "Reusable React + Web Worker scaffolding for in-browser ttsc playgrounds built on @ttsc/wasm.",
5
5
  "main": "lib/src/index.js",
6
6
  "types": "lib/src/index.d.ts",
@@ -38,7 +38,7 @@
38
38
  "react": "^18.0.0",
39
39
  "react-dom": "^18.0.0",
40
40
  "tgrid": "^1.0.3",
41
- "@ttsc/wasm": "^0.14.0-dev.20260528.1"
41
+ "@ttsc/wasm": "^0.14.0-dev.20260529.1"
42
42
  },
43
43
  "devDependencies": {
44
44
  "@monaco-editor/react": "^4.6.0",
@@ -50,7 +50,7 @@
50
50
  "react-dom": "^18.3.1",
51
51
  "rimraf": "^6.1.2",
52
52
  "tgrid": "^1.0.3",
53
- "@ttsc/wasm": "^0.14.0-dev.20260528.1"
53
+ "@ttsc/wasm": "^0.14.0-dev.20260529.1"
54
54
  },
55
55
  "keywords": [
56
56
  "ttsc",