Skip to content

Commit f7dda87

Browse files
hatemhosnyhatemhosny
committed
Merge branch 'develop'
1 parent 6a797ff commit f7dda87

351 files changed

Lines changed: 63197 additions & 37634 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/_artifacts/domain_map.yaml‎

Lines changed: 798 additions & 0 deletions
Large diffs are not rendered by default.

‎.agents/skills/_artifacts/skill_spec.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# LiveCodes — Skill Spec
2+
3+
LiveCodes is a feature-rich, open-source, client-side code playground that runs in the browser. It supports 90+ languages/frameworks, provides powerful SDK for embedding, and requires no server or build step.
4+
5+
## Domains
6+
7+
| Domain | Description | Skills |
8+
| -------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------- |
9+
| SDK and Embedding | Creating, configuring, and communicating with embedded playgrounds | sdk-embedding, sdk-methods, framework-wrappers, headless-mode |
10+
| Configuration | Configuring playground behavior through config objects and query params | configuration, display-modes |
11+
| Languages and Compilation | Working with 90+ supported languages, compilers, processors, and module resolution | language-support, module-resolution, testing |
12+
| Integration and Deployment | Integrating with documentation sites, frameworks, and self-hosting | markdown-integration, self-hosting, import-export |
13+
14+
## Skill Inventory
15+
16+
| Skill | Type | Domain | What it covers | Failure modes |
17+
| -------------------- | ----------- | ------------- | ---------------------------------------------------------------------------- | ------------- |
18+
| livecodes | core | - | Overview, quick start, decision tree, key concepts, minimal examples | 3 |
19+
| sdk-embedding | core | sdk-embedding | createPlayground, getPlaygroundUrl, compress, decompress, EmbedOptions, container setup, loading modes, appUrl | 4 |
20+
| sdk-methods | core | sdk-embedding | run, getCode, setConfig, watch, runTests, format, getShareUrl, show, destroy | 3 |
21+
| framework-wrappers | framework | sdk-embedding | React, Vue, Svelte, Solid, Preact, Web Components SDK usage | 2 |
22+
| headless-mode | core | sdk-embedding | Creating playgrounds without UI, load() requirement, compiled output | 1 |
23+
| configuration | core | configuration | Config object, EmbedOptions, query params, editor/app/user config | 3 |
24+
| display-modes | core | configuration | full, focus, simple, lite, editor, codeblock, result modes | 0 |
25+
| language-support | core | languages | Language names/aliases, compilers, CSS processors, WASM languages | 2 |
26+
| module-resolution | core | languages | npm/deno/jsr/GitHub imports, CDN providers, import maps, #nobundle | 3 |
27+
| testing | core | languages | Jest, Testing Library, watch mode, running tests programmatically | 0 |
28+
| markdown-integration | composition | integration | remark-livecodes, markdown-it-livecodes, Docusaurus, Astro, VitePress | 0 |
29+
| self-hosting | composition | integration | Deploying to static servers, Docker, BASE_URL, SDK appUrl config | 1 |
30+
| gh-action | composition | integration | Preview in LiveCodes GitHub Action, PR comments, workflow setup | 3 |
31+
| import-export | core | configuration | GitHub/GitLab imports, URL imports, DOM imports, export formats | 0 |
32+
| getting-started | lifecycle | - | Quick start for standalone, embedding, and self-hosting | 0 |
33+
34+
## Failure Mode Inventory
35+
36+
### livecodes (3 failure modes)
37+
38+
| # | Mistake | Priority | Source | Cross-skill |
39+
| --- | ---------------------------------------- | -------- | ---------------------------- | ------------- |
40+
| 1 | SDK methods not awaited | HIGH | Documentation: sdk/js-ts.mdx | sdk-methods |
41+
| 2 | Container element not found throws error | HIGH | Source code: sdk/index.ts | sdk-embedding |
42+
| 3 | Config vs EmbedOptions confusion | HIGH | Documentation: sdk/js-ts.mdx | configuration |
43+
44+
### sdk-embedding (4 failure modes)
45+
46+
| # | Mistake | Priority | Source | Cross-skill |
47+
| --- | ------------------------------------------------ | -------- | --------------------------------- | ------------- |
48+
| 1 | Container element not found throws error | HIGH | Source code: sdk/index.ts | sdk-methods |
49+
| 2 | Invalid appUrl throws error | MEDIUM | Source code: sdk/index.ts | sdk-embedding |
50+
| 3 | Calling SDK methods after destroy() throws error | HIGH | Source code: sdk/index.ts | sdk-methods |
51+
| 4 | SDK method timeout after 60 seconds | MEDIUM | Source code: API_TIMEOUT constant | sdk-methods |
52+
53+
### sdk-methods (3 failure modes)
54+
55+
| # | Mistake | Priority | Source | Cross-skill |
56+
| --- | -------------------------------------------------- | -------- | ---------------------------- | ----------- |
57+
| 1 | Not awaiting async SDK methods | HIGH | Documentation: sdk/js-ts.mdx | sdk-methods |
58+
| 2 | watch() callback receives undefined/malformed data | MEDIUM | Documentation: sdk/js-ts.mdx | sdk-methods |
59+
| 3 | Using deprecated onChange instead of watch | LOW | Source code: sdk/index.ts | sdk-methods |
60+
61+
### configuration (3 failure modes)
62+
63+
| # | Mistake | Priority | Source | Cross-skill |
64+
| --- | ---------------------------------------------------------- | -------- | ------------------------------------ | ---------------- |
65+
| 1 | Confusion between Config and EmbedOptions | HIGH | Documentation: sdk/js-ts.mdx | sdk-embedding |
66+
| 2 | Overriding Config with params creates precedence confusion | MEDIUM | Documentation: sdk/js-ts.mdx | configuration |
67+
| 3 | Incorrect editor language name or alias | MEDIUM | Source code: models.ts Language type | language-support |
68+
69+
### framework-wrappers (2 failure modes)
70+
71+
| # | Mistake | Priority | Source | Cross-skill |
72+
| --- | ------------------------------------------------- | -------- | --------------------------------------------- | ------------------ |
73+
| 1 | Not using sdkReady callback to access SDK methods | HIGH | Documentation: sdk/react.mdx, sdk/vue.mdx | sdk-methods |
74+
| 2 | Changing non-config props causes full reload | MEDIUM | Documentation: sdk/react.mdx - Reactive Props | framework-wrappers |
75+
76+
### headless-mode (1 failure mode)
77+
78+
| # | Mistake | Priority | Source | Cross-skill |
79+
| --- | -------------------------------------------------------- | -------- | ------------------------------- | ----------- |
80+
| 1 | Not calling load() before other methods in headless mode | HIGH | Documentation: sdk/headless.mdx | sdk-methods |
81+
82+
### language-support (2 failure modes)
83+
84+
| # | Mistake | Priority | Source | Cross-skill |
85+
| --- | ------------------------------------- | -------- | ------------------------------------ | ---------------- |
86+
| 1 | CSS processors applied in wrong order | MEDIUM | Documentation: features/css.mdx | language-support |
87+
| 2 | WASM language first load is slow | LOW | Documentation: languages/\*-wasm.mdx | language-support |
88+
89+
### module-resolution (3 failure modes)
90+
91+
| # | Mistake | Priority | Source | Cross-skill |
92+
| --- | ---------------------------------------------------------- | -------- | ------------------------------------ | ----------------- |
93+
| 1 | Importing same module from different CDNs causes conflicts | HIGH | Documentation: module-resolution.mdx | module-resolution |
94+
| 2 | CommonJS require not converted to ESM properly | LOW | Documentation: module-resolution.mdx | module-resolution |
95+
| 3 | Not using #nobundle for pre-bundled imports | LOW | Documentation: module-resolution.mdx | module-resolution |
96+
97+
### self-hosting (1 failure mode)
98+
99+
| # | Mistake | Priority | Source | Cross-skill |
100+
| --- | ------------------------------------------------- | -------- | ---------------------------------------- | ------------ |
101+
| 1 | Not configuring BASE_URL for subdirectory hosting | MEDIUM | Documentation: features/self-hosting.mdx | self-hosting |
102+
103+
### gh-action (3 failure modes)
104+
105+
| # | Mistake | Priority | Source | Cross-skill |
106+
| --- | ------------------------------------ | -------- | ---------------------------------- | ----------- |
107+
| 1 | Workflow files not on default branch | HIGH | GitHub Actions: workflow_run event | gh-action |
108+
| 2 | Missing permissions for PR comments | MEDIUM | GitHub Actions: permissions | gh-action |
109+
| 3 | Using data URLs for large files | MEDIUM | Action: dpaste.com limits | gh-action |
110+
111+
## Tensions
112+
113+
| Tension | Skills | Agent implication |
114+
| -------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
115+
| SDK embedding vs Markdown integration | sdk-embedding, markdown-integration | Agents may mix up createPlayground with markdown-it-livecodes; need to clarify when to use each |
116+
| Configuration complexity vs Quick start simplicity | configuration, getting-started | Agents should start with templates/params, then graduate to full Config objects |
117+
| Self-hosted appUrl vs CDN-hosted app | self-hosting, module-resolution | App URL affects share URLs, short URLs, and module resolution behavior |
118+
119+
## Cross-References
120+
121+
| From | To | Reason |
122+
| ------------------ | ---------------- | ------------------------------------------------------------------------ |
123+
| sdk-embedding | sdk-methods | Creating a playground is prerequisite to using SDK methods |
124+
| sdk-methods | configuration | setConfig and getConfig require understanding Config object structure |
125+
| framework-wrappers | sdk-methods | sdkReady callback provides access to SDK methods in framework components |
126+
| module-resolution | language-support | CDN resolution behaves differently for different language types |
127+
| headless-mode | sdk-methods | Headless mode relies entirely on SDK methods; no UI available |
128+
| getting-started | sdk-embedding | Quick start leads directly to embedding basics |
129+
| display-modes | configuration | Mode is a config option; understand alongside other config |
130+
131+
## Subsystems & Reference Candidates
132+
133+
| Skill | Subsystems | Reference candidates |
134+
| ----------------- | ------------------------------------------------------ | ----------------------------------------------- |
135+
| configuration | Content Config, Editor Config, App Config, User Config | — |
136+
| language-support | — | Language aliases (90+), Processor configuration |
137+
| sdk-methods | — | Method signatures (10+ SDK methods) |
138+
| module-resolution | — | CDN providers (10+), Import map format |
139+
140+
## Remaining Gaps
141+
142+
| Skill | Question | Status |
143+
| ------------------ | ---------------------------------------------------------------------------- | ------ |
144+
| sdk-methods | What are the most common SDK method errors users encounter? | open |
145+
| language-support | Are there language-specific quirks that frequently confuse users? | open |
146+
| framework-wrappers | Do any frameworks have specific reactivity or lifecycle issues with the SDK? | open |
147+
148+
## Recommended Skill File Structure
149+
150+
- **Core skills:** sdk-embedding, sdk-methods, configuration, language-support, module-resolution, testing
151+
- **Framework skills:** framework-wrappers
152+
- **Lifecycle skills:** getting-started
153+
- **Composition skills:** markdown-integration, self-hosting, import-export
154+
- **Specialized skills:** headless-mode, display-modes
155+
- **Reference candidates needed:** Languages reference (90+ language names, aliases, extensions), CDN Providers reference
156+
157+
## Composition Opportunities
158+
159+
| Library | Integration points | Composition skill needed |
160+
| -------------- | ---------------------------- | ------------------------ |
161+
| React | React SDK wrapper component | framework-wrappers |
162+
| Vue | Vue SDK wrapper component | framework-wrappers |
163+
| Svelte | Svelte SDK wrapper component | framework-wrappers |
164+
| Solid | Solid SDK wrapper component | framework-wrappers |
165+
| Preact | Preact SDK wrapper component | framework-wrappers |
166+
| Docusaurus | remark-livecodes plugin | markdown-integration |
167+
| Astro | remark-livecodes plugin | markdown-integration |
168+
| VitePress | markdown-it-livecodes plugin | markdown-integration |
169+
| Next.js | remark-livecodes plugin | markdown-integration |
170+
| Storybook | remark-livecodes plugin | markdown-integration |
171+
| react-markdown | remark-livecodes plugin | markdown-integration |

0 commit comments

Comments
 (0)