From 16aeaecaf97e4eaf5388e41affa0b083881ac0ea Mon Sep 17 00:00:00 2001 From: Kinflou <149606337+Kinflou@users.noreply.github.com> Date: Sat, 14 Nov 2026 21:53:46 +0800 Subject: [PATCH] Design: the playground and tutorial share comline-web-kit The playground's editor and simulate view are now a package, comline-web-kit, that the tutorial installs by git (ComlineProject/playground#118), and the tutorial's "Try it" lesson runs on the view's lesson layout. - playground-and-tutorial.md: "Not sharing yet" becomes what's shared and how; the reality note and the framework decision say the shared part is framework-neutral TS, with no Svelte component library. - brand-assets.md: shared-web is no longer a consumer or the planned relay; the kit's --cl-* properties are where shared colours belong. --- docs/docs/design/brand-assets.md | 16 +++++----- docs/docs/design/playground-and-tutorial.md | 35 ++++++++++++--------- 2 files changed, 29 insertions(+), 22 deletions(-) diff --git a/docs/docs/design/brand-assets.md b/docs/docs/design/brand-assets.md index 85e2e96..21eae3f 100644 --- a/docs/docs/design/brand-assets.md +++ b/docs/docs/design/brand-assets.md @@ -3,8 +3,7 @@ Status: **In use** — `ComlineProject/brand` holds the canonical files; the docs site vendors the mark and favicon from it. Other consumers still carry their own copies · Affects `ComlineProject/brand`, `ComlineProject/docs`, -`ComlineProject/package-registry-frontend`, `ComlineProject/shared-web`, -`ComlineProject/comline` +`ComlineProject/package-registry-frontend`, `ComlineProject/comline` ## The problem @@ -74,7 +73,6 @@ instead. |---|---|---| | `docs` | `docs/docs/assets/` | `mkdocs.yml` `theme.logo` / `theme.favicon` | | `package-registry-frontend` | `static/images/comline/`, `static/favicon.*` | header bar, `app.html` | -| `shared-web` | per its own convention | shared web components | | `comline` (landing) | `static/` | header, hero | ## Follow-ups @@ -83,12 +81,14 @@ instead. `palette.primary` to a custom tomato (`--md-primary-fg-color: #E5442E`) would put the header on-brand; it needs a contrast check against the header text and the two colour schemes before it lands. -- **`shared-web` as the web consumers' relay.** If the playground, tutorial, and - landing site end up sharing a component layer (`shared-web`), that layer — not - each app — should carry the one vendored copy. +- **`comline-web-kit` as the web consumers' relay.** The playground and the + tutorial share `comline-web-kit` (a workspace of `ComlineProject/playground`), + whose views take their colours from `--cl-*` custom properties. Brand colours + that more than one site needs belong in the kit's defaults, not in each app. + `shared-web`, the earlier attempt at a shared layer, was never used. - **`tokens.json` → build input.** Nothing consumes `tokens.json` yet. A web build could generate a CSS custom-property file from it so the colours are never retyped. -- **Other consumers.** `package-registry-frontend`, `shared-web`, and the - landing site still carry their originals; each should re-copy from `brand` and +- **Other consumers.** `package-registry-frontend` and the landing site still + carry their originals; each should re-copy from `brand` and add a provenance note the way the docs site now does. diff --git a/docs/docs/design/playground-and-tutorial.md b/docs/docs/design/playground-and-tutorial.md index 0a20c3b..72678b6 100644 --- a/docs/docs/design/playground-and-tutorial.md +++ b/docs/docs/design/playground-and-tutorial.md @@ -198,22 +198,29 @@ work on the analysis layer benefits both. validators → imports → generate → runtime. The `tutorial` README wants each step to *simulate* running machines with distinct local/remote panels and live stats — the loopback runtime above is the engine for that. -- **Not sharing yet, in practice.** The one lesson built so far ("two services - talk") is a standalone widget (`ComlineProject/tutorial`'s - `Simulation.svelte`) driving `comline-simulator` directly — it reuses neither - the playground's `comline-playground-wasm` (the editor) nor its `sim/ui/*.ts` - components. The "same WASM module and component library" plan below hasn't - materialised for the runtime piece; revisit once more lessons exist. +- **Shared through `comline-web-kit`.** The playground's editor and simulate + view are a package, `comline-web-kit`: a workspace of + `ComlineProject/playground` that other sites install by git, the way they + install `comline-simulator` + ([playground#118](https://github.com/ComlineProject/playground/issues/118)). + - `comline-web-kit/sim` is the simulate view. Its **lesson layout** shows a + fixed scene from a session link: no palette, nothing to add, move or + remove, only a server's behaviours and a client's calls, stacked in one + column and fitted to the page. The tutorial's "Try it" lesson runs on it. + - `comline-web-kit/editor` is the CodeMirror editor and the compile + worker. No lesson uses it yet; a lesson with a live editor will. + - `comline-web-kit/sim.css` is scoped under `.cl-sim` and themed with + `--cl-*` properties, so the tutorial keeps its own palette. ## Where it lives / embedding **Reality diverged from the "SvelteKit for both" plan below.** The playground ended up Vite + vanilla TS + CodeMirror (see the status line above); only the -tutorial is SvelteKit. There's no neutral TS package or shared Svelte component -library — the tutorial's one interactive lesson so far is a standalone widget -against `comline-simulator` directly (see -[Playground vs tutorial](#playground-vs-tutorial)). The plan as originally -written: +tutorial is SvelteKit. What's shared is the plan's first half: a +framework-neutral TS package, `comline-web-kit`, that both apps mount (see +[Playground vs tutorial](#playground-vs-tutorial)). The second half, a Svelte +component library, isn't needed: a Svelte page mounts the kit's views through an +action. The plan as originally written: **SvelteKit for the apps, framework-neutral for what's shared.** The `playground` and `tutorial` stay SvelteKit (the existing scaffold). Below them: @@ -242,9 +249,9 @@ subdomains. - **Target** — everything: compile + diagnostics + codegen + a runtime demo. No cut-down first release; the runtime demo simply fills in per language. - **Framework** — *superseded in practice*: the playground shipped Vite + - vanilla TS + CodeMirror, not SvelteKit; only the tutorial is SvelteKit, and - its one interactive lesson is a standalone widget, not a shared component - library. See [Where it lives / embedding](#where-it-lives-embedding). + vanilla TS + CodeMirror, not SvelteKit; only the tutorial is SvelteKit. They + share framework-neutral TS, `comline-web-kit`, not a component library. See + [Where it lives / embedding](#where-it-lives-embedding). ## Findings so far