@tai42/studio-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,15 @@
+tai-studio
+Copyright 2026 tai42
+
+This product includes software developed at tai42 (https://tai42.ai).
+Licensed under the Apache License, Version 2.0.
+
+This product bundles the following third-party fonts, each licensed under the
+SIL Open Font License, Version 1.1. The full licence text ships beside the font
+binaries at `/licenses/` in the built application.
+
+Inter
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+Geist Mono
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)

package/README.md

@@ -0,0 +1,318 @@
+# @tai42/studio-sdk
+
+The Studio plugin surface: everything a Studio plugin (and every built-in
+feature) is allowed to touch. It defines the plugin API a plugin implements — the
+`PluginContext` its `register` entry receives, the contribution types, and the
+version-compatibility gate — and ships the shared design-system components,
+hooks, and schema-driven auto-form that features and plugins build on.
+
+The host-only registry (`loadPlugin`/`getContributions`) is deliberately absent
+from the main entry so a served plugin asset cannot forge, wipe, or enumerate the
+registry; it lives only behind the `@tai42/studio-sdk/host` entry that the host
+bundle imports. See the repository `SECURITY.md` for the trust boundary.
+
+## Install
+
+```bash
+pnpm add @tai42/studio-sdk
+```
+
+## Entry points
+
+- `@tai42/studio-sdk` — the plugin API, design system, and hooks.
+- `@tai42/studio-sdk/host` — the host-only plugin registry.
+- `@tai42/studio-sdk/testing` — test-only helpers: a registry reset and
+  `installJsdomStubs()`, which fills the browser APIs jsdom omits.
+- `@tai42/studio-sdk/tokens.css` — the design-token stylesheet. It also emits the
+  canonical `@layer` order, so a host imports it FIRST.
+- `@tai42/studio-sdk/fonts.css` — the self-hosted Inter Variable and Geist Mono
+  Variable faces, loaded once per host app.
+- `@tai42/studio-sdk/components.css` — the component, layout, responsive, and
+  prose classes the design system is drawn with. It is **not class-only**: in the
+  `tai-components` layer it also styles bare `h1`–`h6` (colour, size, weight,
+  `letter-spacing`), `::selection`, Chromium's `input:-webkit-autofill`, and —
+  below 640 px, so the mobile top bar cannot cover a jump target — `html`'s
+  `scroll-padding-top` plus `scroll-margin-top` on `:target` and `#main-content`.
+  It also declares one private custom property, `--shell-topbar-height`, on
+  `:root`. All of it sits in `tai-components`, which outranks a host preflight in
+  `base` — so a host that wants its OWN heading or selection rules to win has to
+  place them after this sheet, not in `base`.
+
+A host that bundles the SDK gets all three through the barrel's side-effect
+imports. A host that consumes the SDK as an external module (the Studio shell
+resolves it through the served import map) imports the three stylesheets itself.
+
+## Browser support
+
+The stylesheets ship as authored, with no build-time lowering, so the CSS they
+use is the support floor: **Chrome/Edge 99, Firefox 97, Safari and iOS Safari
+15.4**, set by `@layer` and `:focus-visible`. The same floor is declared in this
+package's `browserslist`.
+
+Theming deliberately does not use `light-dark()`. That function would fold each
+light/dark pair onto one line, but it is invalid at computed-value time below
+Chrome 123 / Firefox 120 / Safari 17.5 — and because every themed token would use
+it, the whole palette would drop out at once below that line, leaving text on
+text. Instead the dark value sits beside the light one under a `--tai-dark-` name
+and is applied by a `prefers-color-scheme` query plus a `[data-theme="dark"]`
+block, so each colour is still written exactly once. The Studio SHELL sits higher
+than the SDK — it compiles Tailwind v4, whose output needs `@property` and
+`color-mix()` — and declares that floor in the repository root's `browserslist`.
+
+## Design tokens
+
+`tokens.css` is the styling API: a plugin styles against these names and gets
+whichever half the viewer's theme resolves to. The names are also exported as
+`TOKEN_NAMES` (86 of them), and the list grows additively — a rename or a removal
+bumps the SDK compatibility version.
+
+The light value is the token; the dark value sits beside it under a
+`--tai-dark-` name that a plugin never reads. Two blocks put the dark half into
+service — a `prefers-color-scheme: dark` query for the OS preference and a
+`[data-theme="dark"]` block for the viewer's explicit choice — and neither
+carries a value of its own, so a pair cannot drift apart. A token whose dark
+column reads _(same)_ below is either an alias of another token or deliberately
+one value in both themes.
+
+**The values below are the contract, and `tokens.css` is where they are
+authored.** `token-usage.test.ts` pins them there in both directions: a kept name
+given a new value and a token declared with a value nobody recorded fail alike.
+
+**Grounds**
+
+| Token                          | Light                      | Dark      |
+| ------------------------------ | -------------------------- | --------- |
+| `--tai-color-bg`               | `#ffffff`                  | `#0c0e12` |
+| `--tai-color-surface`          | `#f9fafb`                  | `#12151b` |
+| `--tai-color-surface-raised`   | `#ffffff`                  | `#171c24` |
+| `--tai-color-surface-disabled` | `var(--tai-color-surface)` | _(same)_  |
+| `--tai-color-code-bg`          | `#f3f4f6`                  | `#10131a` |
+
+**Lines.** `border` and `border-strong` are decorative — both sit below 3:1 and
+may never be a control's only boundary. `control-border` is the contrast-safe
+one for inputs, checkboxes and secondary buttons.
+
+| Token                         | Light                     | Dark      |
+| ----------------------------- | ------------------------- | --------- |
+| `--tai-color-border`          | `#e5e7eb`                 | `#262c36` |
+| `--tai-color-border-strong`   | `#d1d5db`                 | `#39414e` |
+| `--tai-color-control-border`  | `#767c85`                 | `#646c79` |
+| `--tai-color-border-disabled` | `var(--tai-color-border)` | _(same)_  |
+
+**Ink.** `decor` is the NON-TEXT tier — dividers, watermarks, decorative SVG
+fill or stroke. It never appears on `color:` and never identifies a component or
+a state.
+
+| Token                       | Light                         | Dark                        |
+| --------------------------- | ----------------------------- | --------------------------- |
+| `--tai-color-text`          | `#111827`                     | `#e6e8ec`                   |
+| `--tai-color-heading`       | `#000000`                     | `#ffffff`                   |
+| `--tai-color-text-muted`    | `rgba(17, 24, 39, 0.62)`      | `rgba(230, 232, 236, 0.64)` |
+| `--tai-color-text-disabled` | `rgba(17, 24, 39, 0.38)`      | `rgba(230, 232, 236, 0.36)` |
+| `--tai-color-placeholder`   | `var(--tai-color-text-muted)` | _(same)_                    |
+| `--tai-color-decor`         | `rgba(17, 24, 39, 0.44)`      | `rgba(230, 232, 236, 0.42)` |
+
+**Accent.** The accent is brand, never status. `accent-on-tint` is accent TEXT
+on `accent-tint`; `on-accent` is the label on an accent FILL.
+
+| Token                        | Light                     | Dark                       |
+| ---------------------------- | ------------------------- | -------------------------- |
+| `--tai-color-accent`         | `#dc143c`                 | `#ed4c67`                  |
+| `--tai-color-accent-hover`   | `#800020`                 | `#f4718a`                  |
+| `--tai-color-accent-on-tint` | `#be123c`                 | `#f4718a`                  |
+| `--tai-color-on-accent`      | `#ffffff`                 | `#0c0e12`                  |
+| `--tai-color-accent-tint`    | `rgba(220, 20, 60, 0.08)` | `rgba(237, 76, 103, 0.12)` |
+
+**Semantic.** The `-text` members are the only ones legible as text, dots or
+icons; the `-fill` members are for fills and charts and carry `on-fill` ink.
+
+| Token                   | Light                     | Dark                        |
+| ----------------------- | ------------------------- | --------------------------- |
+| `--tai-color-ok-text`   | `#047857`                 | `#34d399`                   |
+| `--tai-color-err-text`  | `#b91c1c`                 | `#f87171`                   |
+| `--tai-color-warn-text` | `#92400e`                 | `#fbbf24`                   |
+| `--tai-color-ok-fill`   | `#10b981`                 | `#34d399`                   |
+| `--tai-color-err-fill`  | `#ef4444`                 | `#f87171`                   |
+| `--tai-color-warn-fill` | `#d97706`                 | `#fbbf24`                   |
+| `--tai-color-ok-tint`   | `rgba(16, 185, 129, 0.1)` | `rgba(52, 211, 153, 0.12)`  |
+| `--tai-color-err-tint`  | `rgba(239, 68, 68, 0.1)`  | `rgba(248, 113, 113, 0.12)` |
+| `--tai-color-warn-tint` | `rgba(217, 119, 6, 0.1)`  | `rgba(251, 191, 36, 0.12)`  |
+| `--tai-color-on-fill`   | `#0c0e12`                 | _(same)_                    |
+
+**Focus, overlay, prose and syntax**
+
+| Token                          | Light                         | Dark                 |
+| ------------------------------ | ----------------------------- | -------------------- |
+| `--tai-color-focus-ring`       | `var(--tai-color-accent)`     | _(same)_             |
+| `--tai-color-scrim`            | `rgba(0, 0, 0, 0.45)`         | `rgba(0, 0, 0, 0.6)` |
+| `--tai-color-prose-link`       | `#dc143c`                     | `#f4718a`            |
+| `--tai-color-prose-link-hover` | `#800020`                     | `#ed4c67`            |
+| `--tai-color-syntax-key`       | `var(--tai-color-text-muted)` | _(same)_             |
+| `--tai-color-syntax-string`    | `var(--tai-color-ok-text)`    | _(same)_             |
+| `--tai-color-syntax-number`    | `var(--tai-color-accent)`     | _(same)_             |
+| `--tai-color-syntax-bool`      | `var(--tai-color-warn-text)`  | _(same)_             |
+
+**Legacy slots.** The names a plugin already styles against, re-pointed at the
+members of the contract above that keep them legible.
+
+| Token                        | Light                        | Dark      |
+| ---------------------------- | ---------------------------- | --------- |
+| `--tai-color-primary`        | `var(--tai-color-accent)`    | _(same)_  |
+| `--tai-color-primary-text`   | `var(--tai-color-on-accent)` | _(same)_  |
+| `--tai-color-danger`         | `var(--tai-color-err-text)`  | _(same)_  |
+| `--tai-color-danger-text`    | `#ffffff`                    | `#0c0e12` |
+| `--tai-color-danger-hover`   | `#7f1d1d`                    | `#fca5a5` |
+| `--tai-color-danger-surface` | `var(--tai-color-err-tint)`  | _(same)_  |
+| `--tai-color-success`        | `var(--tai-color-ok-text)`   | _(same)_  |
+| `--tai-color-warning`        | `var(--tai-color-warn-text)` | _(same)_  |
+
+**Spacing** (n × 4; there is deliberately no `space-7`). Authored in `rem` so a
+viewer's font-size preference scales them; the px column is the rendered size at
+a 16 px root.
+
+| Token           | Value     | at 16px |
+| --------------- | --------- | ------- |
+| `--tai-space-1` | `0.25rem` | 4px     |
+| `--tai-space-2` | `0.5rem`  | 8px     |
+| `--tai-space-3` | `0.75rem` | 12px    |
+| `--tai-space-4` | `1rem`    | 16px    |
+| `--tai-space-5` | `1.25rem` | 20px    |
+| `--tai-space-6` | `1.5rem`  | 24px    |
+| `--tai-space-8` | `2rem`    | 32px    |
+
+**Type.** Line-height and weight are deliberately NOT in the tokens — the
+component classes own them, so a `font:` shorthand never resets them.
+
+| Token                | Value                                                                                       | at 16px                                 |
+| -------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `--tai-font-sans`    | `'Inter Variable', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif` | —                                       |
+| `--tai-font-mono`    | `'Geist Mono Variable', ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, monospace`        | —                                       |
+| `--tai-text-display` | `1.625rem`                                                                                  | 26px — KPI numbers                      |
+| `--tai-text-xl`      | `1.4375rem`                                                                                 | 23px — page title                       |
+| `--tai-text-section` | `1.0625rem`                                                                                 | 17px — section heading                  |
+| `--tai-text-lg`      | `0.9375rem`                                                                                 | 15px — card title                       |
+| `--tai-text-md`      | `0.84375rem`                                                                                | 13.5px — body                           |
+| `--tai-text-sm`      | `0.78125rem`                                                                                | 12.5px — secondary                      |
+| `--tai-text-code`    | `0.75rem`                                                                                   | 12px — mono blocks                      |
+| `--tai-text-xs`      | `0.6875rem`                                                                                 | 11px — labels, badges, axes (the floor) |
+
+**Radius, control geometry and motion.** Under `prefers-reduced-motion` both
+motion durations resolve to `0ms`, so CSS written against them honours the
+preference without reading the media query.
+
+| Token                         | Value   |
+| ----------------------------- | ------- |
+| `--tai-radius-sm`             | `4px`   |
+| `--tai-radius-code`           | `6px`   |
+| `--tai-radius-md`             | `8px`   |
+| `--tai-radius-tile`           | `10px`  |
+| `--tai-radius-lg`             | `12px`  |
+| `--tai-radius-overlay`        | `14px`  |
+| `--tai-radius-full`           | `999px` |
+| `--tai-control-height`        | `36px`  |
+| `--tai-control-height-coarse` | `44px`  |
+| `--tai-motion-fast`           | `150ms` |
+| `--tai-motion-base`           | `250ms` |
+
+**Elevation.** Only the shadow COLOUR varies by theme; the geometry is written
+once, so a dark override cannot silently move an offset or a blur. `shadow-sm`
+and `shadow-md` are legacy slots that now alias the lift and overlay geometry.
+
+| Token                        | Light                                         | Dark                |
+| ---------------------------- | --------------------------------------------- | ------------------- |
+| `--tai-shadow-lift-color`    | `rgb(0 0 0 / 0.08)`                           | `rgb(0 0 0 / 0.45)` |
+| `--tai-shadow-overlay-color` | `rgb(0 0 0 / 0.16)`                           | `rgb(0 0 0 / 0.6)`  |
+| `--tai-shadow-lift`          | `0 12px 32px var(--tai-shadow-lift-color)`    | _(same)_            |
+| `--tai-shadow-overlay`       | `0 24px 48px var(--tai-shadow-overlay-color)` | _(same)_            |
+| `--tai-shadow-sm`            | `var(--tai-shadow-lift)`                      | _(same)_            |
+| `--tai-shadow-md`            | `var(--tai-shadow-overlay)`                   | _(same)_            |
+
+**Stacking.** `popover` and `tooltip` sit ABOVE the modal layers on purpose: both
+portal to the document body as siblings of a dialog and have to clear its scrim
+to be usable. `dropdown` is the rung reserved for an in-flow menu surface —
+nothing in the SDK is on it, so a plugin's own menu has a rung to sit on instead
+of inventing a number.
+
+| Token              | Value |
+| ------------------ | ----- |
+| `--tai-z-sticky`   | `10`  |
+| `--tai-z-dropdown` | `20`  |
+| `--tai-z-overlay`  | `30`  |
+| `--tai-z-dialog`   | `40`  |
+| `--tai-z-popover`  | `45`  |
+| `--tai-z-tooltip`  | `50`  |
+
+## The shell classes
+
+`components.css` also publishes the application-shell chrome, so a host can lay
+out its own sidebar, brand lockup and top bar on the same geometry the Studio
+uses. These classes are CSS only — the SDK ships no shell component, and the host
+owns the markup.
+
+| Class                             | What it is                                                                                               |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `.tai-shell`                      | The two-column grid: a sidebar track plus `minmax(0, 1fr)` for the page.                                 |
+| `.tai-shell-sidebar`              | The sticky, full-height, scrollable nav column.                                                          |
+| `.tai-shell-main`                 | The page track (`min-width: 0`, so a wide child scrolls itself instead of the document).                 |
+| `.tai-brand`                      | The brand lockup, a link home; sits in the tab order ahead of the nav and carries the shared focus ring. |
+| `.tai-brand-mark`                 | The 24 px mark inside it.                                                                                |
+| `.tai-brand-label`                | Its wordmark; hidden in the icon rail.                                                                   |
+| `.tai-nav-item` / `.tai-nav-link` | One nav row. Two names for the same rule.                                                                |
+| `.tai-nav-section-header`         | The uppercase mono heading over a nav group; hidden in the icon rail.                                    |
+| `.tai-topbar`                     | The sticky bar shown INSTEAD of the sidebar below 640 px.                                                |
+| `.tai-skip-link`                  | Skip-to-content: off-screen until focused.                                                               |
+
+**Geometry.** A 232 px sidebar at 1024 px and up; a 72 px icon rail from 640 px
+that KEEPS a short text label under each icon (a touch band is never
+tooltip-only); below 640 px the sidebar is `display: none` and `.tai-topbar`
+becomes a sticky 56 px bar.
+
+**Host prerequisites** — the shell classes assume all of these, and none of them
+is something the sheet can supply for you:
+
+1. **Import order.** `tokens.css` first (it emits the canonical `@layer` order),
+   then `components.css`. A host preflight that resets borders and heading
+   typography must be in the `base` layer, which sorts before them.
+2. **A height to fill.** `.tai-shell` is `min-height: 100%`, so `html` and `body`
+   need a height for it to reach the viewport. The sidebar sets its own
+   `100dvh` (with a `100vh` fallback for browsers below the `dvh` floor).
+3. **No clipping ancestor.** `.tai-shell-sidebar` is `position: sticky; top: 0` —
+   an ancestor with `overflow` other than `visible` silently un-sticks it.
+4. **`aria-current="page"` on the current nav row.** All three current-item cues
+   (the accent tint, the accent-on-tint ink, the inset rail) key off that
+   attribute, not off a class, so assistive tech and the rendering cannot
+   disagree.
+5. **The skip link is first.** `.tai-skip-link` has to be the first focusable
+   element in the shell and to target the main region, or WCAG 2.4.1 is not met
+   by rendering it. Below 640 px the sheet reserves the top bar's height with
+   `scroll-padding-top`, and gives `:target` and `#main-content` a matching
+   `scroll-margin-top` — so the main region wants `id="main-content"`.
+6. **A nav surface below 640 px.** The sidebar is hidden there and the sheet
+   styles the bar, not what opens from it. Below 640 px a host that renders
+   `.tai-topbar` and nothing else has NO reachable navigation — the sheet cannot
+   supply one. The SDK exports `Drawer` (with the `.tai-drawer` rules already in
+   this sheet) as the intended vehicle, but nothing in the SDK mounts it: the
+   host renders it and drives its `open` state itself.
+7. **Nav icons carry no margin of their own.** `.tai-nav-item` is a flex row and
+   already sets the icon-to-label gap from the spacing scale; a margin beside the
+   icon is additive and sets that row apart from every other one.
+8. **The rail rules are scoped.** The 72 px band's rules apply to
+   `.tai-shell-sidebar` DESCENDANTS, so a host that lays its sidebar out itself
+   keeps the full-width nav rendering at every width instead of getting
+   column-stacked 11 px labels.
+9. **`--shell-topbar-height` is private to the sheet**, deliberately outside the
+   `--tai-*` contract. Do not read it; it is not part of the published API.
+
+## Usage
+
+```ts
+import type { PluginEntry } from '@tai42/studio-sdk';
+
+export const register: PluginEntry = (ctx) => {
+  ctx.registerPage({ path: 'dashboard', title: 'Dashboard', component: MyDashboard });
+};
+```
+
+## License
+
+Apache-2.0. See the repository `LICENSE`.

package/SECURITY.md

@@ -0,0 +1,51 @@
+# Plugin security / trust boundary
+
+`@tai42/studio-sdk` ships as three entry points, split along a trust boundary:
+
+- **`@tai42/studio-sdk`** — the plugin surface. Types, `PluginContext`/`PluginEntry`,
+  contribution types, the design system, and hooks. This is the only entry a
+  Studio plugin is allowed to import, and it is the single served vendor asset
+  (`/vendor/studio-sdk.js`) every plugin bundle binds through the import map.
+- **`@tai42/studio-sdk/host`** — the host-only registry API: `loadPlugin` (the one
+  entry a plugin's `register` contributes through) and `getContributions` (what the
+  shell reads). Served as `/vendor/studio-sdk-host.js` and imported only by the host
+  shell.
+- **`@tai42/studio-sdk/testing`** — a test-only registry reset (`__resetContributions`).
+  Never served to the browser.
+
+## Why the split
+
+The in-memory registry lives in one module and is a singleton across the plugin
+boundary. If a plugin could import `loadPlugin`/`getContributions`, a compromised
+bundle could forge, wipe, or enumerate every plugin's contributions. Keeping the
+registry API on `@tai42/studio-sdk/host` means the served plugin asset carries no
+registry at all — the registry state exists in exactly one served asset
+(`/vendor/studio-sdk-host.js`).
+
+## How the boundary is enforced
+
+- **At plugin ingest** — the skeleton rejects any plugin bundle that references
+  a host-only subpath (`@tai42/studio-sdk/host` or `@tai42/studio-sdk/testing`). This
+  is the real enforcement.
+- **At dev time** — an ESLint `no-restricted-imports` rule forbids plugin source
+  from importing `@tai42/studio-sdk/host` or `@tai42/studio-sdk/testing`, so an author
+  hits the wall before publishing.
+
+## Threat model
+
+The current model trusts installed plugins: they come from a curated registry,
+are SRI-pinned, and are reviewed before install. Under that model the split
+above is sufficient.
+
+The shipped marketplace surface stays inside that model. It browses one curated
+registry, and every install, update, and uninstall runs on the host backend
+through its authed `/api/marketplace/*` routes — the browser never fetches or
+installs a bundle itself. The backend resolves the listing to a pinned version,
+refuses a non-withdrawn critical advisory, downloads the registry-named artifact,
+and verifies its sha256 against the digest the registry captured at release
+before anything is installed.
+
+What would need stronger isolation is an OPEN submission model — anyone
+publishing a plugin that installs without review. That would call for per-plugin
+iframe or worker sandboxing so a hostile bundle cannot reach shared page state at
+all. That is tracked as future work.

package/dist/components/badge.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `Badge` — a small tinted label. `variant` is a free string (extension "kind"
+ * values map straight to it); known variants get a themed tint plus its
+ * matching text color from the design-system classes, and any other value falls
+ * back to the neutral tint.
+ */
+import type { ReactNode } from 'react';
+export interface BadgeProps {
+    readonly variant?: string;
+    readonly children: ReactNode;
+}
+export declare function Badge({ variant, children }: BadgeProps): import("react").JSX.Element;
+//# sourceMappingURL=badge.d.ts.map

package/dist/components/badge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../src/components/badge.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAaD,wBAAgB,KAAK,CAAC,EAAE,OAAmB,EAAE,QAAQ,EAAE,EAAE,UAAU,+BAMlE"}

package/dist/components/badge.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const NEUTRAL_CLASS = 'tai-badge tai-badge-neutral';
+/** `primary` is the base badge: the accent tint needs no modifier class. */
+const VARIANT_CLASS = {
+    neutral: NEUTRAL_CLASS,
+    primary: 'tai-badge',
+    success: 'tai-badge tai-badge-ok',
+    warning: 'tai-badge tai-badge-warn',
+    danger: 'tai-badge tai-badge-err',
+};
+export function Badge({ variant = 'neutral', children }) {
+    return (_jsx("span", { "data-variant": variant, className: VARIANT_CLASS[variant] ?? NEUTRAL_CLASS, children: children }));
+}
+//# sourceMappingURL=badge.js.map

package/dist/components/badge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../src/components/badge.tsx"],"names":[],"mappings":";AAaA,MAAM,aAAa,GAAG,6BAA6B,CAAC;AAEpD,4EAA4E;AAC5E,MAAM,aAAa,GAA2B;IAC5C,OAAO,EAAE,aAAa;IACtB,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,wBAAwB;IACjC,OAAO,EAAE,0BAA0B;IACnC,MAAM,EAAE,yBAAyB;CAClC,CAAC;AAEF,MAAM,UAAU,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAc;IACjE,OAAO,CACL,+BAAoB,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,IAAI,aAAa,YAC5E,QAAQ,GACJ,CACR,CAAC;AACJ,CAAC"}

package/dist/components/checkbox.d.ts

@@ -0,0 +1,24 @@
+export interface CheckboxProps {
+    /**
+     * `'indeterminate'` is the MIXED state a parent box wears while only some of
+     * the children it governs are checked. Radix reports it as
+     * `aria-checked="mixed"`; clicking it resolves to checked, which is why the
+     * change callback stays boolean.
+     */
+    readonly checked?: boolean | 'indeterminate';
+    readonly defaultChecked?: boolean;
+    readonly onCheckedChange?: (checked: boolean) => void;
+    readonly disabled?: boolean;
+    readonly label?: string;
+    /**
+     * Accessible name for a checkbox with no visible `label` (e.g. a table cell).
+     * An enclosing `Field` wins where both are given — it names the box from
+     * visible text, and `aria-label` would override that native label and leave
+     * the visible text out of the accessible name (WCAG 2.5.3).
+     */
+    readonly 'aria-label'?: string;
+    readonly name?: string;
+    readonly value?: string;
+}
+export declare function Checkbox({ checked, defaultChecked, onCheckedChange, disabled, label, 'aria-label': ariaLabel, name, value, }: CheckboxProps): import("react").JSX.Element;
+//# sourceMappingURL=checkbox.d.ts.map

package/dist/components/checkbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../../src/components/checkbox.tsx"],"names":[],"mappings":"AAoBA,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EACP,cAAc,EACd,eAAe,EACf,QAAQ,EACR,KAAK,EACL,YAAY,EAAE,SAAS,EACvB,IAAI,EACJ,KAAK,GACN,EAAE,aAAa,+BAwCf"}