@aliens-syndicate/cli 0.1.1 → 0.1.3

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 (29) hide show
  1. package/README.md +122 -93
  2. package/package.json +6 -2
  3. package/tools/build.mjs +326 -26
  4. package/tools/cli.mjs +31 -9
  5. package/tools/create.mjs +38 -12
  6. package/tools/icon-docs.mjs +132 -0
  7. package/tools/runtime.mjs +216 -8
  8. package/tools/starter/ai/agents/codingbot.agent +5 -0
  9. package/tools/starter/ai/rules/architecture.rule +11 -0
  10. package/tools/starter/ai/skills/create-element.skill +6 -0
  11. package/tools/starter/app/elements/molecules/kit-card-link/kit-card-link.markup +0 -2
  12. package/tools/starter/app/pages/kit-overview/kit-overview.markup +6 -6
  13. package/tools/starter/app/pages/style-guide/style-guide.style +57 -57
  14. package/tools/starter/styles/components/alerts.style +6 -5
  15. package/tools/starter/styles/components/badges.style +6 -5
  16. package/tools/starter/styles/components/borders.style +2 -1
  17. package/tools/starter/styles/components/buttons.style +14 -13
  18. package/tools/starter/styles/components/cards.style +1 -1
  19. package/tools/starter/styles/components/feedback.style +3 -2
  20. package/tools/starter/styles/components/forms.style +5 -4
  21. package/tools/starter/styles/components/tables.style +4 -3
  22. package/tools/starter/styles/components/typography.style +6 -5
  23. package/tools/starter/styles/generic/ui-base.style +1 -1
  24. package/tools/starter/styles/objects/ui-layout.style +1 -1
  25. package/tools/style-docs.mjs +274 -0
  26. package/tools/vscode-space/package.json +5 -8
  27. package/tools/vscode-space/space.tmLanguage.json +1 -1
  28. package/tools/vscode-space/syntax.cjs +103 -62
  29. package/tools/watch.mjs +48 -0
package/README.md CHANGED
@@ -1,41 +1,43 @@
1
- # Aliens Framework · Documentação
1
+ # Aliens Framework · Documentation
2
2
 
3
- Os fontes da aplicação ficam em `project/`. As páginas ficam em `project/app/pages/` e os Elements reutilizáveis em `project/app/elements/`. As imagens ficam em `project/assets/`, as traduções em `project/language/` e os estilos globais em `project/styles/`. O build lê `.config` e gera `ai/.map` para o CodingBot. Os dois arquivos usam caminhos relativos à raiz do workspace. As ferramentas do Space ficam em `tools/`, ao lado de `project/`.
3
+ **English** · [Português](README.pt-BR.md) · [Español](README.es-ES.md) · [中文](README.zh-CN.md)
4
4
 
5
- ## Criar um projeto
5
+ Application sources live in `project/`. Pages live in `project/app/pages/` and reusable Elements in `project/app/elements/`. Images live in `project/assets/`, translations in `project/language/` and global styles in `project/styles/`. The build reads `.config` and generates `ai/.map` for the CodingBot. Both files use paths relative to the workspace root. The Space tools live in `tools/`, next to `project/`.
6
+
7
+ ## Create a project
6
8
 
7
9
  ```sh
8
- node tools/create.mjs meu-projeto
9
- cd meu-projeto
10
+ node tools/create.mjs my-project
11
+ cd my-project
10
12
  node tools/build.mjs
11
13
  ```
12
14
 
13
- Depois da publicação do pacote `@aliens-syndicate/cli` no npm, o mesmo gerador fica disponível sem clonar o repositório. O comando `aliens build` executa o `tools/build.mjs` do projeto aberto.
15
+ The same generator is published on npm as `@aliens-syndicate/cli` and works without cloning the repository. The `aliens build` command runs the `tools/build.mjs` of the project you are in. `aliens watch` (or `node tools/watch.mjs`) rebuilds `dist/` and `ai/.map` on every saved file. Comments that start with `#AGENT` are directives for AI agents only: the build lists them, with file and line, under `directives:` in `ai/.map`.
14
16
 
15
17
  ```sh
16
- npx @aliens-syndicate/cli create meu-projeto
17
- cd meu-projeto
18
+ npx @aliens-syndicate/cli create my-project
19
+ cd my-project
18
20
  npx @aliens-syndicate/cli build
19
21
  ```
20
22
 
21
- Para publicar uma nova versão, atualize `version` em `package.json` e execute `npm publish` na raiz, com a conta `aliens-syndicate` logada no npm.
23
+ To publish a new version, update `version` in `package.json` and run `npm publish` at the root, with the `aliens-syndicate` account logged in to npm.
22
24
 
23
- O gerador cria a Home em `project/app/pages/home/`, os quatro níveis de Elements e as pastas dos tipos de arquivo da aplicação. Os exemplos comentados do catálogo de heróis vêm da base do motor em `tools/starter/`, independente da aplicação que estiver aberta. O Element `hero-card` reúne `.markup`, `.logic`, `.style` e `.test` em `project/app/elements/molecules/hero-card/`. As pastas `agents/`, `rules/` e `skills/` ficam em `ai/`.
25
+ The generator creates the Home in `project/app/pages/home/`, the four Element levels and the folders for the application file types. The commented examples of the hero catalog come from the engine base in `tools/starter/`, regardless of the application you have open. The `hero-card` Element brings together `.markup`, `.logic`, `.style` and `.test` in `project/app/elements/molecules/hero-card/`. The `agents/`, `rules/` and `skills/` folders live in `ai/`.
24
26
 
25
- Cada exemplo tem uma descrição seguida de uma linha que contém apenas `#`. Para experimentar, remova o prefixo `# ` das linhas de código abaixo dessa linha, preservando os três espaços por nível. No cartão, descomente `hero-card.markup`, `hero-card.logic` e `hero-card.style` e inclua `hero-card` no markup de uma página.
27
+ Each example has a description followed by a line that contains only `#`. To try it, remove the `# ` prefix from the code lines below that line, keeping three spaces per level. In the card, uncomment `hero-card.markup`, `hero-card.logic` and `hero-card.style` and add `hero-card` to a page's markup.
26
28
 
27
- Em `project/app/routes/`, os exemplos comentados mostram rotas fixas e filhas, parâmetros, filtros, redirecionamento, guard, estado e fallback. A execução de rotas e de arquivos `.test` faz parte do trabalho pendente no runtime.
29
+ In `project/app/routes/`, the commented examples show fixed and child routes, parameters, filters, redirects, guards, state and fallback. Running routes and `.test` files is part of the pending runtime work.
28
30
 
29
- ## Biblioteca de estilos e temas
31
+ ## Style library and themes
30
32
 
31
- Cada projeto novo abre com uma biblioteca navegável em Space, com sete vistas e exemplos em português, inglês, espanhol e chinês. No site da documentação, o botão **Biblioteca de estilos** na Home abre `#kit-overview`.
33
+ Every new project opens with a browsable style library written in Space, with seven views and examples in Portuguese, English, Spanish and Chinese. On the documentation site, the **Style library** button on the Home opens `#kit-overview`.
32
34
 
33
- - `project/styles/settings/` reúne os tokens de cor, espaço, raio, borda, tipografia e elevação.
34
- - `project/styles/components/` fornece tipografia H1–H6, parágrafo, texto auxiliar, legenda, link, lista, citação e código; botões, campos, cartões, etiquetas, avisos, bordas, espaçamento, tabela, progresso e painel expansível.
35
- - `project/styles/settings/theme.style` centraliza os valores semânticos dos temas `light` e `dark` da biblioteca. Os componentes usam esses valores por meio de variáveis CSS.
36
- - `project/app/pages/kit-*/` contém as páginas de amostras. Os Elements reutilizáveis ficam nos níveis do Atomic Design.
35
+ - `project/styles/settings/` holds the color, spacing, radius, border, typography and elevation tokens.
36
+ - `project/styles/components/` provides H1–H6 typography, paragraph, helper text, caption, link, list, quote and code; buttons, fields, cards, badges, alerts, borders, spacing, table, progress and expandable panel.
37
+ - `project/styles/settings/theme.style` centralizes the semantic values of the library's `light` and `dark` themes. Components use these values through CSS variables.
38
+ - `project/app/pages/kit-*/` contains the sample pages. Reusable Elements live in the Atomic Design levels.
37
39
 
38
- Para criar outro tema, acrescente um bloco ao final de `theme.style`, com um nome em letras minúsculas, números e hífens, começando por letra. Os valores não redefinidos herdam a base clara de `:root`. Para um tema escuro completo, copie o bloco `dark`, troque o nome e personalize seus tokens.
40
+ To create another theme, add a block at the end of `theme.style`, with a name made of lowercase letters, numbers and hyphens, starting with a letter. Values you don't redefine inherit the light base from `:root`. For a complete dark theme, copy the `dark` block, rename it and customize its tokens.
39
41
 
40
42
  ```text
41
43
  :root[data-theme="ocean"]
@@ -48,44 +50,44 @@ Para criar outro tema, acrescente um bloco ao final de `theme.style`, com um nom
48
50
  --color-on-accent: #0c4a6e
49
51
  ```
50
52
 
51
- Execute o build após editar. O motor reconhece os blocos do arquivo e adiciona os temas ao seletor, mantendo a preferência entre recarregamentos. As amostras exibem o código real dos arquivos `.style`. A base do gerador fica em `tools/starter/`; personalizações de um projeto não são copiadas para os projetos seguintes.
53
+ Run the build after editing. The engine recognizes the blocks in the file and adds the themes to the picker, keeping the preference across reloads. The samples show the real code of the `.style` files. The generator base lives in `tools/starter/`; customizations to one project are not copied to the next ones.
52
54
 
53
55
  ## Atomic Design
54
56
 
55
- - `atoms/` contém elementos básicos, como botões, links e controles de tema.
56
- - `molecules/` contém componentes de função específica, como busca, seletor de idioma e contador.
57
- - `organisms/` contém composições como cabeçalho, menu lateral, grade de guias e playground.
58
- - `templates/` contém o layout reutilizável dos painéis de referência.
57
+ - `atoms/` contains basic elements, such as buttons, links and theme controls.
58
+ - `molecules/` contains components with a specific job, such as search, language picker and counter.
59
+ - `organisms/` contains compositions such as the header, guide grid and playground.
60
+ - `templates/` contains the reusable layout of the reference panels.
59
61
 
60
- O catálogo de tipos fica em `project/app/pages/type-index/`, junto às páginas, e usa o template `type-summary` para montar os painéis navegáveis. Cada Element mantém seus arquivos Space na própria pasta.
62
+ The type catalog lives in `project/app/pages/type-index/`, next to the pages, and uses the `type-summary` template to build the navigable panels. Each Element keeps its Space files in its own folder.
61
63
 
62
- ## Padrão Space
64
+ ## Space conventions
63
65
 
64
- O cabeçalho dos arquivos nomeados começa com o tipo e o nome em PascalCase. O corpo usa três espaços por nível. Campos e contratos usam tipos explícitos. Comentários declarativos começam com `#`.
66
+ The header of named files starts with the type and the name in PascalCase. The body uses three spaces per level. Fields and contracts use explicit types. Declarative comments start with `#`.
65
67
 
66
68
  ```text
67
69
  Markup App
68
70
  home
69
71
  ```
70
72
 
71
- O exemplo está em `project/app/app.markup`. Outros cabeçalhos são `Logic App`, `Style App` e `Pipe Currency`. `.config`, `.env`, `ai/.map` e os arquivos de tradução têm suas próprias estruturas Space. O build valida cabeçalho e indentação nos fontes do projeto. Os exemplos de código usam a paleta do Space nos dois temas.
73
+ The example is in `project/app/app.markup`. Other headers are `Logic App`, `Style App` and `Pipe Currency`. `.config`, `.env`, `ai/.map` and the translation files have their own Space structures. The build validates headers and indentation in the project sources. Code examples use the Space palette in both themes.
72
74
 
73
- ### Nomes: element-filho_modificador:estado
75
+ ### Names: element-child_modifier:state
74
76
 
75
- O `.markup`, o `.style` e o `.logic` usam os mesmos nomes, sempre em minúsculas. Cada separador tem um papel:
77
+ `.markup`, `.style` and `.logic` use the same names, always in lowercase. Each separator has a role:
76
78
 
77
- | Conceito | Separador | Exemplo |
79
+ | Concept | Separator | Example |
78
80
  | --- | --- | --- |
79
- | Element | nenhum além do próprio nome | `site-header` |
80
- | Filho | `-` | `site-header-logo` |
81
- | Modificador | `_` | `site-header-logo_large` |
82
- | Estado | `:` | `site-header-logo_large:hover` |
81
+ | Element | none besides its own name | `site-header` |
82
+ | Child | `-` | `site-header-logo` |
83
+ | Modifier | `_` | `site-header-logo_large` |
84
+ | State | `:` | `site-header-logo_large:hover` |
83
85
 
84
- A ordem é `element-filho_modificador:estado`. Pastas e arquivos de Elements seguem o nome do Element, como `site-header/site-header.markup`. O build reconhece o Element pelo nome conhecido: `site-header-logo` pertence a `site-header`. Cada nome tem no máximo um modificador. O estado é uma pseudo-classe do CSS e aparece apenas no `.style`.
86
+ The order is `element-child_modifier:state`. Element folders and files follow the Element name, as in `site-header/site-header.markup`. The build recognizes the Element by its known name: `site-header-logo` belongs to `site-header`. Each name has at most one modifier. The state is a CSS pseudo-class and appears only in `.style`.
85
87
 
86
88
  #### Markup
87
89
 
88
- O `id` nomeia uma tag. O `variant` nomeia um estilo compartilhado por várias tags. O markup não aceita `class`. Um nome começa pelo Element que o escreve, por um Element que o renderiza ou pela biblioteca `space`. O modificador já traz a base: `variant="counter-button_increase"` gera `class="counter-button counter-button_increase"`.
90
+ `id` names one tag. `variant` names a style shared by several tags. Markup does not accept `class`. A name starts with the Element that writes it, an Element that renders it or the `space` library. A modifier brings its base along: `variant="counter-button_increase"` generates `class="counter-button counter-button_increase"`.
89
91
 
90
92
  ```text
91
93
  Markup Counter
@@ -96,32 +98,35 @@ Markup Counter
96
98
  button variant="counter-button_increase" action="increment" text="+" label={@counter.increment}
97
99
  ```
98
100
 
99
- O build recusa a página quando um `id` se repete, quando um nome é `id` e `variant` ao mesmo tempo, quando coincide com uma tag HTML ou quando sai do formato.
101
+ The build rejects the page when an `id` repeats, when a name is both an `id` and a `variant`, when it matches an HTML tag or when it breaks the format.
100
102
 
101
103
  #### Style
102
104
 
103
- Escreva o nome sem `#` ou `.`. O build gera `[id="nome"]` para um `id` e `.nome` para um `variant`, com o mesmo peso no cascade. Para combinar dois nomes na mesma tag, use `:is()`, como em `space-card:is(space-border_strong)`. Nomes que não são `id`, `variant` nem tag HTML geram erro. Os estilos globais de `project/styles/` declaram os variants da biblioteca, sempre com o prefixo `space-`, como `space-button_primary`.
105
+ Write the name without `#` or `.`. The build generates `[id="name"]` for an `id` and `.name` for a `variant`, with the same weight in the cascade. To combine two names on the same tag, use `:is()`, as in `space-card:is(space-border_strong)`. Names that are not an `id`, a `variant` or an HTML tag raise an error. The global styles in `project/styles/` declare the library variants, always with the `space-` prefix, such as `space-button_primary`.
104
106
 
105
107
  ```text
106
108
  Style Counter
107
109
  counter-button
108
- border: 1px solid var(--line-strong)
110
+ flex items-center gap-2 px-4 py-2 border border-(--line-strong) rounded-lg
111
+ hover:border-(--accent-stroke) max-md:w-full
109
112
  counter-button_increase
110
- background: var(--primary)
111
- counter-button:hover
112
- border-color: var(--accent-stroke)
113
+ bg-(--primary) text-(--primary-ink)
113
114
  ```
114
115
 
116
+ Inside a selector, a line written as `property: value` is a CSS declaration. By default `.style` reads plain CSS only. Utilities are optional and live in their own package: install `@aliens-syndicate/style` and declare it in `.config` under `style:` with `from: @aliens-syndicate/style`. Without it, a utility line stops the build and says how to add the package. With it, any other line lists utilities with the names popularized by existing CSS frameworks: `flex`, `gap-4`, `rounded-lg`, `text-sm`. Variants such as `md:`, `max-lg:`, `hover:` and `dark:` write the `@media` rule or the selector, and utilities such as `backdrop-blur-md` and `bg-clip-text` add the `-webkit-` declarations. Brackets take any value, as in `w-[1240px]`, and parentheses read a custom property, as in `text-(--muted)`. Each `--color-<name>` in the global styles becomes a color, as in `bg-brand`. An unknown utility stops the build with the file and the line. The **Styles** page of the documentation site (`#style-docs`) lists every class with its CSS; `node tools/style-docs.mjs` regenerates it from the package's catalog.
117
+
118
+ Icons are optional and live in their own package. Install `@aliens-syndicate/icons` and declare it in `.config` under `icons:` with `from: @aliens-syndicate/icons` and a default `style:`. Icons belong to the markup, with no span and no class: `icon add-01 size-4 blue-500 red-500` names the icon and then, in any order, one of the ten styles, a size, up to two colors (the second paints the light tone of bulk, duotone and twotone) and a state such as `disabled` or `hidden`; `id`, `variant` and `label` are its only attributes. The build draws each icon inline, and a project without the package builds the same way. The **Icons** page (`#icon-docs`) lists all 6,070 icons by category and copies the tag of any of them; `node tools/icon-docs.mjs` regenerates it from the package.
119
+
115
120
  #### Logic
116
121
 
117
- `bind:` lista cada `id` do Element com o que um signal define na tag. As expressões usam o mesmo JavaScript do `body:`. Uma entrada `_modificador` liga e desliga o modificador na tag: `_menu-open` em `home` aplica `home_menu-open`. `page:` indica o signal que controla o tema ou o idioma da página.
122
+ `bind:` lists each `id` of the Element with what a signal sets on the tag. Expressions use the same JavaScript as `body:`. A `_modifier` entry toggles the modifier on the tag: `_menu-open` on `site-header` applies `site-header_menu-open`. `page:` names the signal that controls the page theme or language.
118
123
 
119
124
  ```text
120
- Logic Home
125
+ Logic SiteHeader
121
126
  signal menuOpen: boolean = false
122
127
 
123
128
  bind:
124
- home:
129
+ site-header:
125
130
  _menu-open: this.menuOpen
126
131
  site-header-menu-toggle:
127
132
  expanded: this.menuOpen
@@ -133,88 +138,112 @@ Logic Home
133
138
  this.menuOpen = !this.menuOpen
134
139
  ```
135
140
 
136
- | Em `bind:` | Efeito na tag |
141
+ | In `bind:` | Effect on the tag |
137
142
  | --- | --- |
138
- | `text` | Troca o texto pelo valor. |
139
- | `show` | Mostra a tag quando o valor é verdadeiro. |
140
- | `pressed` | Define `aria-pressed`. |
141
- | `expanded` | Define `aria-expanded`. |
142
- | `_modificador` | Aplica `id_modificador` enquanto o valor for verdadeiro. |
143
+ | `text` | Replaces the text with the value. |
144
+ | `show` | Shows the tag when the value is true. |
145
+ | `pressed` | Sets `aria-pressed`. |
146
+ | `expanded` | Sets `aria-expanded`. |
147
+ | `_modifier` | Applies `id_modifier` while the value is true. |
148
+
149
+ An `id` in the `<element>-<signal>` format needs no `bind:` for text: `counter-value` shows `value` in Counter. In an action body, `element("counter-title")` returns the tag. `bind:` reaches the tags of the Element itself and those of child Elements without `.logic`. The attributes `data-show`, `data-pressed`, `data-expanded`, `data-state`, `data-bind`, `data-theme-control` and `data-language` are not accepted in markup. Signals and actions are JavaScript identifiers and stay in camelCase, such as `menuOpen` and `toggleMenu`.
150
+
151
+ Native tags accept the same short properties as Elements: `variant` becomes `class`, `action` becomes `data-action`, `label` becomes `aria-label` and `text` becomes the tag text. `button` gets `type="button"` when it declares no `type`.
152
+
153
+ #### Lists and for
143
154
 
144
- Um `id` no formato `<element>-<signal>` dispensa o `bind:` para texto: `counter-value` exibe `value` em Counter. No corpo de uma ação, `element("counter-title")` devolve a tag. O `bind:` alcança as tags do próprio Element e as de Elements filhos sem `.logic`. Os atributos `data-show`, `data-pressed`, `data-expanded`, `data-state`, `data-bind`, `data-theme-control` e `data-language` não são aceitos no markup. Signals e actions são identificadores JavaScript e continuam em camelCase, como `menuOpen` e `toggleMenu`.
155
+ `list <name>:` in a `.logic` declares a fixed list. Each item has a name, and that name is its identity: there is no `track` to declare. In markup, `for <item> in <list>` repeats the tags below it, and each field is read as `{$item.field}`.
156
+
157
+ ```text
158
+ Logic SiteHeader
159
+ list links:
160
+ agent:
161
+ href: #agent
162
+ label: @nav.agent
163
+ files:
164
+ href: #files-index
165
+ label: @nav.files
166
+ ```
167
+
168
+ ```text
169
+ Markup SiteHeader
170
+ nav id="site-header-nav"
171
+ for link in links
172
+ nav-item href={$link.href} label={$link.label}
173
+ ```
145
174
 
146
- Tags nativas aceitam as mesmas propriedades curtas dos Elements: `variant` vira `class`, `action` vira `data-action`, `label` vira `aria-label` e `text` vira o texto da tag. `button` recebe `type="button"` quando não declara `type`.
175
+ The build writes the item name as `data-key` on the first tag of each repetition. `{$item.key}` and `{$item.index}` (starting at zero) are built in, so `key` and `index` can't be field names. The list comes from the `.logic` of the Element or of an Element around it. Duplicate names, missing fields, and unknown lists stop the build with file and line. Lists render with the page; the runtime doesn't update them yet.
147
176
 
148
- ### Elements com os arquivos necessários
177
+ ### Elements with only the files they need
149
178
 
150
- Um Element é o conjunto de arquivos com o mesmo nome na mesma pasta. Nenhum arquivo é obrigatório, e o build reconhece cada um pelo nome e pela extensão.
179
+ An Element is the set of files with the same name in the same folder. No file is required, and the build recognizes each one by its name and extension.
151
180
 
152
- | Arquivos | O que o Element faz |
181
+ | Files | What the Element does |
153
182
  | --- | --- |
154
- | `badge.markup` e `badge.style` | Renderiza estrutura e aparência. |
155
- | `counter.markup`, `counter.logic` e `counter.style` | Renderiza e reage a ações. |
156
- | `session.logic` | Executa uma instância única para a página e não renderiza nada. |
157
- | `spinner.style` | Fornece variants com o nome do Element, como `spinner` e `spinner_large`. |
183
+ | `badge.markup` and `badge.style` | Renders structure and appearance. |
184
+ | `counter.markup`, `counter.logic` and `counter.style` | Renders and reacts to actions. |
185
+ | `session.logic` | Runs a single instance for the page and renders nothing. |
186
+ | `spinner.style` | Provides variants named after the Element, such as `spinner` and `spinner_large`. |
158
187
 
159
- - **Element só com `.logic`:** o markup chama as ações com o nome do Element, como em `action="session.logout"`. O `page:` também funciona. Como não há tags, o `bind:` gera erro.
160
- - **Element só com `.style`:** qualquer markup aplica os nomes com `variant="spinner_large"`. O `.style` só declara nomes que começam pelo próprio Element.
161
- - **Erros de uso:** usar como tag um Element sem `.markup`, como `spinner` ou `session`, gera erro. O mesmo vale para tags que não são HTML nem Element, e para Elements com nome de tag HTML, como `button`.
188
+ - **Element with only `.logic`:** markup calls its actions with the Element name, as in `action="session.logout"`. `page:` works too. Since there are no tags, `bind:` raises an error.
189
+ - **Element with only `.style`:** any markup applies its names with `variant="spinner_large"`. The `.style` only declares names that start with the Element itself.
190
+ - **Usage errors:** using an Element without `.markup`, such as `spinner` or `session`, as a tag raises an error. The same applies to tags that are neither HTML nor an Element, and to Elements named after an HTML tag, such as `button`.
162
191
 
163
- O build valida por necessidade. Cada `action` de uma tag renderizada precisa existir no `.logic` do próprio Element ou de um Element ao redor dela. Uma action com nome de Element, como `session.logout`, precisa existir nesse Element. Um erro de digitação aparece no build, com arquivo e linha.
192
+ The build validates by need. Every `action` of a rendered tag must exist in the `.logic` of its own Element or of an Element around it. An action with an Element name, such as `session.logout`, must exist in that Element. A typo shows up in the build, with file and line.
164
193
 
165
- A compilação é seletiva. O build valida todos os arquivos, mas o resultado inclui apenas:
194
+ Compilation is selective. The build validates every file, but the output includes only:
166
195
 
167
- - os estilos e a lógica dos Elements que a página renderiza;
168
- - os Elements só com `.style` cujos nomes alguma tag usa;
169
- - os Elements só com `.logic` que alguma tag chama ou que declaram `page:`.
196
+ - the styles and logic of the Elements the page renders;
197
+ - the `.style`-only Elements whose names some tag uses;
198
+ - the `.logic`-only Elements that some tag calls or that declare `page:`.
170
199
 
171
- Os estilos globais de `project/styles/` entram sempre.
200
+ The global styles in `project/styles/` are always included.
172
201
 
173
- ## Editor Space
202
+ ## Space editor
174
203
 
175
- A extensão em `tools/vscode-space/` registra o modo Space e o realce semântico no editor. Nos arquivos `.style`, os literais em hexadecimal, RGB, HSL e os nomes CSS em propriedades de cor recebem amostras interativas. O seletor edita apenas o literal escolhido e preserva a transparência em hexadecimal.
204
+ The extension in `tools/vscode-space/` registers the Space mode and semantic highlighting in the editor. In `.style` files, hexadecimal, RGB and HSL literals and CSS color names in color properties get interactive swatches. The picker edits only the chosen literal and preserves hexadecimal transparency.
176
205
 
177
- Instale a extensão no perfil do editor para que os arquivos abram em modo Space nas janelas normais. Com `vsce` disponível, execute `vsce package` em `tools/vscode-space/` e use **Install from VSIX** no painel de extensões. Recarregue a janela e confirme **Space** na barra de status.
206
+ Install the extension in your editor profile so files open in Space mode in normal windows. With `vsce` available, run `vsce package` in `tools/vscode-space/` and use **Install from VSIX** in the extensions panel. Reload the window and confirm **Space** in the status bar.
178
207
 
179
- Para desenvolver a extensão, abra uma janela temporária do VS Code a partir da pasta que contém `project/` e `tools/`.
208
+ To develop the extension, open a temporary VS Code window from the folder that contains `project/` and `tools/`.
180
209
 
181
210
  ```sh
182
211
  code --extensionDevelopmentPath="$PWD/tools/vscode-space" "$PWD"
183
212
  ```
184
213
 
185
- Abra `project/styles/settings/tokens.style` e clique na amostra ao lado de uma cor. O gerador inclui a extensão e a paleta semântica do Space em `.vscode/settings.json`.
214
+ Open `project/styles/settings/tokens.style` and click the swatch next to a color. The generator includes the extension and the Space semantic palette in `.vscode/settings.json`.
186
215
 
187
- ## Abrir a prévia
216
+ ## Open the preview
188
217
 
189
- Na pasta que contém `project/` e `tools/`, gere a página e abra o resultado no Chrome. A prévia foi verificada com Node.js 26.13.0.
218
+ In the folder that contains `project/` and `tools/`, generate the page and open the result in Chrome. The preview was verified with Node.js 26.13.0.
190
219
 
191
220
  ```sh
192
221
  node tools/build.mjs
193
222
  open -a "Google Chrome" dist/index.html
194
223
  ```
195
224
 
196
- Para testar via HTTP, execute `python3 -m http.server 4173 --bind 127.0.0.1 --directory dist` e abra [a prévia local](http://127.0.0.1:4173/). Depois de editar arquivos Space, execute o build de novo e recarregue.
225
+ To test over HTTP, run `python3 -m http.server 4173 --bind 127.0.0.1 --directory dist` and open [the local preview](http://127.0.0.1:4173/). After editing Space files, run the build again and reload.
197
226
 
198
- ## O que entrou
227
+ ## What's included
199
228
 
200
- - Home no formato de landing page, com menu no header (Arquivos, Playground, Styles, Markup, Logic, idioma e tema), caixa para copiar o comando de instalação e seções sobre IA, Elements sem arquivos obrigatórios, o melhor de cada framework e a linguagem Space. A página Arquivos lista os 25 tipos com busca, e cada link leva ao painel do tipo. A busca fica no header e abre com ⌘K ou Ctrl+K. As páginas Para agentes de IA (`#ai-guide`) e Roadmap (`#roadmap`) ficam no rodapé da Home, e todo bloco de código ganha um botão de copiar. `.logic` tem apresentação, decisões de arquitetura, tutorial e playground.
201
- - Playground com contador funcional e três abas que mostram o conteúdo de `counter.logic`, `counter.markup` e `counter.style` diretamente dos arquivos. Para testar um valor inicial diferente, siga o tutorial, altere o arquivo local e gere a prévia novamente.
202
- - Traduções em inglês, português do Brasil, espanhol e chinês simplificado. A primeira visita usa a preferência do navegador, com inglês como idioma padrão quando nenhuma preferência é compatível. A escolha manual é guardada quando o navegador disponibiliza armazenamento.
229
+ - Home as a landing page, with a header menu (Files, Playground, Styles, Markup, Logic, language and theme), a box to copy the install command and sections about AI, Elements without required files, the best of every framework and the Space language. The Files page lists the 25 types with search, and each link opens the type's panel. Search lives in the header and opens with ⌘K or Ctrl+K. The For AI agents (`#ai-guide`) and Roadmap (`#roadmap`) pages are linked in the Home footer, and every code block has a copy button. `.logic` has an introduction, architecture decisions, a tutorial and a playground.
230
+ - Playground with a working counter and three tabs that show the contents of `counter.logic`, `counter.markup` and `counter.style` straight from the files. To try a different initial value, follow the tutorial, change the local file and generate the preview again.
231
+ - Translations in English, Brazilian Portuguese, Spanish and Simplified Chinese. The first visit uses the browser preference, with English as the default when no preference matches. A manual choice is saved when the browser provides storage.
203
232
 
204
- ## O que o protótipo revelou
233
+ ## What the prototype revealed
205
234
 
206
- - A ferramenta do `aliens-exemplo` demonstrava apenas a compilação das folhas de estilo. A prévia em `tools/` foi criada para renderizar a composição de Elements, aplicar traduções, executar ações do contador e alternar os painéis. O código da interface permanece nos arquivos de cada Element.
207
- - O markup chama as ações com `action` e o `.logic` liga os signals às tags por `id`, no bloco `bind:`. Essas convenções, a sintaxe das propriedades de Elements e o formato das traduções precisam de validação antes de virarem parte da gramática definitiva.
208
- - O compilador de prévia cobre os sinais primitivos e as ações sem parâmetros usadas pela documentação. Ele remove anotações TypeScript, sem fazer checagem semântica de tipos. Ciclo de vida, dependências reais entre módulos, serviços e execução de arquivos `.test` ficam pendentes. A navegação da página usa fragmentos de URL. O arquivo `app.route` registra a rota inicial e ainda precisa de um roteador para executá-la.
209
- - O índice segue o catálogo de 25 tipos. `.style` e `.mock` são as extensões definidas para folhas de estilo e dados simulados, respectivamente.
210
- - As abas do playground reaproveitam o código que a página compila. A simulação é interativa e os arquivos são para leitura no navegador. A edição no playground fica para depois que existir uma forma isolada de compilar e executar o código digitado.
235
+ - The `aliens-exemplo` tool only demonstrated stylesheet compilation. The preview in `tools/` was created to render Element composition, apply translations, run the counter actions and switch panels. The interface code stays in each Element's files.
236
+ - Markup calls actions with `action` and `.logic` binds signals to tags by `id`, in the `bind:` block. These conventions, the Element property syntax and the translation format need validation before they become part of the final grammar.
237
+ - The preview compiler covers primitive signals and the parameterless actions used by the documentation. It strips TypeScript annotations without semantic type checking. Lifecycle, real dependencies between modules, services and running `.test` files are pending. Page navigation uses URL fragments. The `app.route` file registers the initial route and still needs a router to run it.
238
+ - The index follows the catalog of 25 types. `.style` and `.mock` are the extensions defined for stylesheets and mock data, respectively.
239
+ - The playground tabs reuse the code the page compiles. The simulation is interactive and the files are read-only in the browser. Editing in the playground waits for an isolated way to compile and run typed code.
211
240
 
212
- ## Validação
241
+ ## Validation
213
242
 
214
- O build passou e o JavaScript gerado foi verificado com `node --check`. No navegador, foram conferidos a Home, o menu em tela pequena, os links do tópico, as abas de código, os cliques e o teclado no contador. A Home final abriu no Chrome em português detectado pelo navegador. No runtime compilado foram verificados sete cenários de preferência de idioma, os quatro seletores manuais e a igualdade entre o código exibido e os três arquivos de origem.
243
+ The build passed and the generated JavaScript was checked with `node --check`. In the browser, the Home, the menu on small screens, the topic links, the code tabs, and clicks and keyboard on the counter were checked. The final Home opened in Chrome in Portuguese detected from the browser. In the compiled runtime, seven language-preference scenarios, the four manual pickers and the match between the displayed code and the three source files were verified.
215
244
 
216
- A biblioteca de estilos foi validada em um projeto novo e em outro criado pelo gerador desse projeto. Foram conferidos os links, IDs únicos, indentação Space, quatro idiomas, H1–H6 em 390 px e sincronização dos seletores de tema. Um tema adicional foi incluído somente no projeto temporário para verificar sua descoberta pelo build e aplicação no navegador.
245
+ The style library was validated in a new project and in another one created by that project's generator. Links, unique IDs, Space indentation, four languages, H1–H6 at 390 px and theme-picker sync were checked. An extra theme was added only to the temporary project to verify its discovery by the build and its application in the browser.
217
246
 
218
- ## Licença
247
+ ## License
219
248
 
220
- O Aliens Framework é distribuído sob a [licença MIT](LICENSE).
249
+ Aliens Framework is distributed under the [MIT license](LICENSE).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@aliens-syndicate/cli",
3
- "version": "0.1.1",
4
- "description": "CLI do Aliens, o framework front-end da era da IA escrito em Space.",
3
+ "version": "0.1.3",
4
+ "description": "CLI for Aliens, the AI-era front-end framework written in Space.",
5
5
  "license": "MIT",
6
6
  "author": "Aliens Syndicate",
7
7
  "type": "module",
@@ -29,5 +29,9 @@
29
29
  "homepage": "https://github.com/AliensSyndicate/aliens-syndicate-framework#readme",
30
30
  "publishConfig": {
31
31
  "access": "public"
32
+ },
33
+ "devDependencies": {
34
+ "@aliens-syndicate/icons": "^0.1.0",
35
+ "@aliens-syndicate/style": "^0.1.0"
32
36
  }
33
37
  }