Feat v0.9.5 typed forms sdk (#79)

Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>

docs/API-REFERENCE.md

@@ -184,3 +184,30 @@ Kernel event prefixes: `user.*`, `team.*`, `workflow.*`, `notification.*`, `pres
 | POST | `/presence/heartbeat` | Update presence status |
 | GET | `/presence` | Query online users |
 | GET | `/users/search` | Search users |
+
+### Forms (v0.9.5)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/forms/validate` | Validate form data against a typed template |
+
+**Request body:**
+
+```json
+{
+  "template": {
+    "fields": [
+      {"key": "name", "type": "text", "label": "Name", "required": true}
+    ]
+  },
+  "data": {"name": "Alice"}
+}
+```
+
+**Response:**
+
+```json
+{"valid": true, "errors": []}
+```
+
+On validation failure, `errors` contains `[{"key": "name", "message": "Name is required"}]`.

docs/FRONTEND-JS-GUIDE.md

@@ -248,6 +248,44 @@ Every surface uses one of three patterns:
 The shell provides the home link, notification bell, and user menu
 on every surface for free.
 
+## `sw.forms` — Typed Forms (v0.9.5)
+
+Any extension can render and validate typed forms using the `sw.forms` module.
+
+### `sw.forms.render(container, template, opts)`
+
+Renders a typed form into a DOM container. Supports flat forms and progressive
+multi-step forms (fieldsets). Returns a control handle.
+
+```js
+const handle = sw.forms.render(document.getElementById('my-form'), template, {
+    values: { name: 'prefilled' },
+    onSubmit: (data) => { console.log('submitted', data); },
+});
+
+// Programmatic access
+const data = handle.getData();
+handle.setErrors([{ key: 'name', message: 'Name is taken' }]);
+handle.destroy();
+```
+
+### `sw.forms.validate(template, data)`
+
+Client-side validation (no network call). Returns `{ valid, errors }`.
+
+```js
+const { valid, errors } = sw.forms.validate(template, { name: '' });
+// valid === false, errors === [{ key: 'name', message: 'Name is required' }]
+```
+
+### `sw.forms.validateRemote(template, data)`
+
+Server-side validation via `POST /api/v1/forms/validate`. Returns a Promise.
+
+```js
+const result = await sw.forms.validateRemote(template, data);
+```
+
 ## Extension CSS contract
 
 Extensions must prefix all CSS classes with `.ext-{slug}-` to avoid

docs/PACKAGE-FORMAT.md

@@ -75,6 +75,7 @@ Only `manifest.json` is required. All other directories are optional and include
 | `contributes` | Slot contributions this package injects into other surfaces |
 | `capabilities` | Environment requirements: `{"required": [...], "optional": [...]}` |
 | `schema_version` | Integer for additive schema migrations |
+| `form_template` | Typed form template (v0.9.5). Fields array or fieldsets for progressive forms. Validated at install. |
 
 ## Multi-Surface Packages
 

docs/STARLARK-REFERENCE.md

@@ -429,3 +429,30 @@ def on_run(ctx):
 
     return {"advance": True, "data": {"needs_review": False}}
 ```
+
+---
+
+## `forms` Module (v0.9.5)
+
+**Permission:** `forms.validate`
+
+Validates form data against a typed form template.
+
+### `forms.validate(template, data)`
+
+Validates `data` (a dict) against a `template` (a dict matching the TypedFormTemplate schema).
+
+Returns a dict: `{"valid": True/False, "errors": [{"key": "...", "message": "..."}]}`.
+
+```python
+result = forms.validate(
+    {"fields": [{"key": "name", "type": "text", "label": "Name", "required": True}]},
+    {"name": "Alice"},
+)
+# result["valid"] == True
+# result["errors"] == []
+```
+
+Field types: `text`, `email`, `select`, `number`, `date`, `textarea`, `checkbox`, `file`.
+
+Supports: required checks, min/max length, pattern (regex), number range, date range, select option whitelist, conditional visibility (`condition.when`/`op`/`value`).