SIMAI Framework IntelliSense 0.1.0: contract 1.3.0, packaging hygiene, registry-driven completions

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Compile and lint
+        run: npm run pretest
+      - name: Unit tests
+        run: npm test
+      - name: Registry parity
+        run: npm run generate:check
+      - uses: actions/cache@v4
+        with:
+          path: .vscode-test
+          key: vscode-test-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Extension-host tests
+        run: xvfb-run -a npm run test:extension
+      - name: Package contents are runtime-only
+        run: npx vsce ls | node out/generate/checkPackage.js
+      - name: Package
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          npx vsce package -o "sf-vscode-${VERSION}.vsix"
+          sha256sum "sf-vscode-${VERSION}.vsix" | tee "sf-vscode-${VERSION}.vsix.sha256"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: vsix
+          path: |
+            *.vsix
+            *.vsix.sha256
+          if-no-files-found: error

.gitignore

@@ -23,6 +23,9 @@ out/
 # Compiled suggestions
 *.vsix
 
+# VS Code test downloads
+.vscode-test/
+
 styles.css
 
 # Compiled Java class files

.vscodeignore

@@ -0,0 +1,13 @@
+# Ship only the runtime. Everything is excluded first, then the runtime
+# files are listed explicitly, so new tooling or local state (for example
+# .simai/, mirai/, work/) can never leak into the package.
+**
+!package.json
+!README.md
+!CHANGELOG.md
+!LICENSE
+!images/icon.png
+!data/*.json
+!out/*.js
+!out/providers/*.js
+!out/registry/*.js

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to SIMAI Framework IntelliSense are listed here.
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Completion for SIMAI Framework `sf-` custom element tags, their attributes
+  and attribute values, from the Framework component manifests.
+- Completion for utility classes in `class`/`className` and as escaped
+  selectors in stylesheets.
+- Completion for every `--sf-` core token and the public component variables,
+  with resolved light/dark and mobile/desktop values.
+- Colour swatches in the completion list and in documents; the colour picker
+  offers the nearest Framework colour tokens.
+- Hovers for tokens, utility classes, tags and attributes with the source
+  release and lifecycle. Deprecated attributes are struck through and name
+  their replacement.
+- Settings `sf.hover.enabled` and `sf.colorSwatches.enabled`.
+
+### Changed
+
+- Renamed the extension to SIMAI Framework IntelliSense and rewrote the
+  README for end users; developer notes moved to CONTRIBUTING.md.
+- Repinned the adaptive sizing contract to `simai.vertical-sizing@1.3.0` from
+  the SIMAI Framework release `ui-a9636b60d3e3` (`simai/ui-source@1d26dd48`).
+- The package now ships only the runtime files.
+- A dot in markup or scripts no longer opens class suggestions; class
+  selectors complete only in stylesheets.
+
+### Fixed
+
+- The first completion request after opening a file no longer comes back
+  empty: the extension activates when VS Code finishes starting and loads its
+  registry on first use.
+
+## [0.0.1]
+
+- Initial preview: adaptive sizing CSS variables.

CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to SIMAI Framework IntelliSense
+
+This guide is for people who build, test or package the extension. The
+end-user documentation is in [README.md](README.md).
+
+## Setup
+
+```sh
+npm install
+```
+
+## Registries
+
+The extension never reads other repositories at runtime. Everything it
+suggests comes from pinned, hash-checked snapshots under `contracts/`, turned
+into the runtime files in `data/` by generators:
+
+| Snapshot | Pointer | Runtime file |
+| --- | --- | --- |
+| `contracts/adaptive-sizing.v1.json` | `contracts/adaptive-sizing.pointer.json` | `data/sf-autocomplete.json` |
+| `contracts/framework/` | `contracts/framework.pointer.json` | `data/sf-framework.json` |
+
+The Framework snapshot holds the contract registry, `core.css`, the public
+component variables, the CSS of the utility families and the manifests of the
+smart components that the registry marks as safe to suggest. Only those
+entries reach `data/sf-framework.json`; blocked entries never do.
+
+Regenerate and verify parity:
+
+```sh
+npm run generate
+npm run generate:check
+```
+
+`generate:check` fails when a snapshot no longer matches its pointer hash or
+when a runtime file is stale.
+
+### Repinning to a new SIMAI Framework release
+
+Take the identity (commit and tree) from the release lock in `simai/ui`
+(`contracts/releases/<release>.lock.json`), never from a moving branch head.
+
+For the adaptive sizing contract, copy the file from the `simai/ui-source`
+commit named under `build_inputs.source`, update the pointer, regenerate and
+run the checks above.
+
+For the Framework snapshot, run the vendor tool against a local `simai/ui`
+clone. It reads every file with `git show` at the commits named by the release
+lock and checks their trees:
+
+```sh
+npm run vendor:framework -- --ui ../ui --release <release> --registry-commit <commit>
+npm run generate
+npm run generate:check
+```
+
+`--registry-commit` is the `simai/ui` commit that binds the contract registry
+to that release.
+
+## Tests
+
+```sh
+npm test               # compile, lint and unit tests
+npm run test:extension # extension-host tests in a downloaded VS Code
+```
+
+The extension-host runner downloads VS Code into `.vscode-test/`. Set
+`VSCODE_EXECUTABLE_PATH` to use an installed build instead, or
+`VSCODE_TEST_VERSION` to pin a version. Set `SF_EXTENSION_PATH` to run the
+suite against another copy of the extension, for example the folder that
+`code --install-extension` created from the packaged `.vsix`. The runner creates a short
+`--user-data-dir` under `/tmp`, because VS Code rejects socket paths longer
+than 103 characters.
+
+## Debugging
+
+Open the folder in VS Code and run **Run extension** (F5).
+
+## Packaging
+
+```sh
+npm run package:ls  # list the files that will ship
+npm run package     # build the .vsix
+```
+
+`.vscodeignore` excludes everything and lists the runtime files explicitly:
+compiled `out/` JavaScript (without tests, generators and source maps), the
+`data/` registries, the README, CHANGELOG, LICENSE and the icon. Publishing to
+the Marketplace happens only after the owner accepts a release.
+
+## Naming
+
+Write the product name as "SIMAI Framework". The technical prefix is `sf`.

README.md

@@ -1,58 +1,68 @@
-# VS Code extension for Simai Framework
+# SIMAI Framework IntelliSense
 
-## Running the Extension for Debugging
+Autocomplete, hovers and colour swatches for
+[SIMAI Framework](https://github.com/simai/ui) in VS Code.
 
-#### 1. Install Dependencies Using the Command
-```sh
-$ npm install
-```
+## Features
+
+### Components
+
+Type `<sf-` in HTML, JSX/TSX or a Vue template to get the SIMAI Framework
+custom elements, such as `sf-button`, `sf-input` or `sf-tabs`. Inside a tag,
+the extension suggests its attributes and, for attributes with a fixed set of
+values, the values themselves:
 
-#### 2. Generate the pinned SF registry
-```sh
-npm run generate
-npm run generate:check
+```html
+<sf-button appearance="tonal" size="1/2" icon-start="check">Save</sf-button>
 ```
 
-Generation uses the vendored, hash-checked
-`simai.vertical-sizing@1.1.0` contract. A local `styles.css` or
-`modifiers.json` is not required. The resulting
-`src/registry/sf-autocomplete.json` preserves mobile and desktop values instead
-of flattening the registry to one resolved mode.
+Deprecated attributes are struck through and name their replacement.
 
-Run the owner checks before debugging:
+### Utility classes
 
-```sh
-npm test
-npm run generate:check
-```
+Utility classes complete in `class` and `className` attributes, including
+breakpoint variants such as `md:flex`. In stylesheets they complete as
+escaped selectors (`.md\:flex`).
 
-#### 3. Launch the Extension in Debugging Mode
-Open the top panel of VS Code, navigate to **Run -> Start Debugging**, or press the **F5** key.
+### Design tokens
 
-## Packaging the VS Code Extension
+Type `var(--sf-` to get every `--sf-*` token of the Framework core: colour
+roles, radius, spacing, typography, control sizes, icons, opacity, z-index,
+elevation and motion, plus the public variables of the components. Each
+suggestion shows its resolved value:
 
-#### 1. Install `vsce`
-```sh
-npm install -g vsce
-```
+- colour tokens show a swatch and their light and dark values;
+- adaptive sizes show their mobile and desktop values.
 
-#### 2. Navigate to the Root Directory of Your Extension Project and Execute the Command
-```sh
-vsce package
-```
-This command will create a `.vsix` file in the current directory. This file contains everything necessary to install your extension.
+Colour tokens in your files get inline swatches. Opening the colour picker
+on one offers the nearest SIMAI Framework colour tokens.
+
+### Hovers
+
+Hover a token, utility class, `sf-` tag or attribute to see what it is, its
+values (light/dark, mobile/desktop), the Framework release it comes from and
+its lifecycle (released, experimental or deprecated).
+
+## Supported languages
+
+CSS, SCSS, Sass, Less, HTML, JavaScript, TypeScript, JSX/TSX and Vue (with a
+Vue language extension installed).
 
-## Installing the Extension via the VS Code Interface
+## Settings
 
-#### 1. Open Visual Studio Code
+| Setting | Default | Description |
+| --- | --- | --- |
+| `sf.hover.enabled` | `true` | Show hovers for tokens, classes, tags and attributes. |
+| `sf.colorSwatches.enabled` | `true` | Show colour swatches next to `--sf-` colour tokens. |
 
-#### 2. Go to the Extensions Section
+## What is suggested
 
-#### 3. Install the Extension from the `.vsix` File
-##### 3.1 Click on the three dots in the top right corner of the Extensions section and select **"Install from VSIX..."**
-##### 3.2 In the opened window, locate and select the downloaded `.vsix` file
-##### 3.3 After installing the extension, you may need to restart VS Code to apply the changes.
+Suggestions come from a pinned, hash-checked snapshot of the SIMAI Framework
+contract registry (release `ui-a9636b60d3e3`). Only entries the Framework marks
+as safe to suggest are offered; blocked and unreleased entries are not.
+Experimental components are labelled as such. The extension does not
+download anything and does not read your other projects.
 
 ## License
 
-The extension is available under the [MIT License](LICENSE).
+[MIT](LICENSE)

contracts/adaptive-sizing.pointer.json

@@ -1,9 +1,10 @@
 {
-  "sourceRepository": "SIMAI/ui-loader",
-  "sourceCommit": "97b3df993a3250661a2d9e9db6500fad16b5b5cb",
-  "sourceTree": "6cc9bda9aae2b5d86918d58c49c736af1708cf7e",
+  "releaseId": "ui-a9636b60d3e3",
+  "sourceRepository": "simai/ui-source",
+  "sourceCommit": "1d26dd483201d24ad1af8419efc21b0d4a76a565",
+  "sourceTree": "5b4d11c91ac0716e083554a9a358b0a9deaadab2",
   "sourcePath": "src/core/contracts/adaptive-sizing.v1.json",
   "contractId": "simai.vertical-sizing",
-  "contractVersion": "1.1.0",
-  "sha256": "333d78f0f3abe6f47c9caa1fc3c53c4d2894e122a922a400804383266cbd72f5"
+  "contractVersion": "1.3.0",
+  "sha256": "b70d02d6902345e17954eafb44f24052b7478439184286bed5a8df6c69c1fe45"
 }