@pieai/swimmer-ui-kit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to `@pieai/swimmer-ui-kit`.
+Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
+
+## 1.0.0 — 2026-07-03
+
+1.0 is a stability contract, not a feature drop: exported components and
+props, `.game-ui-*` class names, and `--game-ui-*` token names are now
+public API — additive-only within the 1.x major. Spec: SPEC-0002.
+
+Distribution is public through npmjs and the source repository is publicly
+readable under the PieAI Limited Use License. This is source-available, not an
+open-source license; bundled visual assets remain restricted.
+
+The npmjs package uses PieAI's existing user scope: `@pieai/swimmer-ui-kit`.
+Earlier GitHub Packages releases used `@pieaistudio/swimmer-ui-kit`; consumers
+moving to npmjs must update the dependency name and import specifiers once.
+
+### Breaking (package identity and packaging)
+
+- **npm scope changed once.** Public npmjs distribution is
+  `@pieai/swimmer-ui-kit`; the earlier `@pieaistudio/swimmer-ui-kit` identity
+  remains only in GitHub Packages history. Consumers must update dependency
+  keys and import specifiers from `@pieaistudio` to `@pieai`.
+
+- **ESM-only.** `dist/index.cjs` and the `require` export condition are
+  removed. Every known consumer is a Vite ESM app; CJS consumers on
+  Node ≥22 can `require(esm)` or use dynamic `import()`.
+- **`./theme.css` subpath removed.** It was a confusing legacy alias of
+  `./styles.css` (verified unused by all consumers). Use `./styles.css`.
+- **Tailwind fully decoupled.** `tailwindcss` and `@tailwindcss/vite`
+  peerDependencies are gone. `dist/styles.css` is now 100% standard CSS —
+  the Tailwind v4 `@theme inline` bridge moved to a new **optional**
+  `./tailwind.css` export (verified unused by all consumers, so no one
+  needs to add it; it exists for future Tailwind hosts that want
+  `bg-primary` etc. to map to kit tokens).
+
+### Fixed
+
+- Vite 8 / lightningcss consumers no longer get "unknown at-rule @theme"
+  warnings: the shipped CSS contains no Tailwind at-rules, and the CSS
+  build itself fails on any lightningcss warning (scripts/build-css.mjs).
+- Type resolution is clean under every strategy (`arethetypeswrong`:
+  node10/node16-ESM/bundler all green; `publint`: zero findings). Types
+  are bundled into one flat `dist/index.d.ts`; the entry no longer leaks
+  `import './styles.css'` into declarations.
+- The published package no longer contains test declarations
+  (`*.test.d.ts`), story files, or `.DS_Store`.
+
+### Added
+
+- Wrapped-app (Capacitor/Tauri WebView) hardening: interactive controls
+  ship `touch-action: manipulation` + transparent tap highlight; game
+  control surfaces (movement pad, toolbars, HUD) are
+  `user-select: none` + `-webkit-touch-callout: none`; hover-lift effects
+  moved behind `@media (hover: hover)` so touch devices never get sticky
+  hover; all safe-area reads flow through `--game-ui-safe-*` tokens
+  (hosts can override the env() source, e.g. Capacitor Android
+  edge-to-edge). All guard-tested in `src/tokens.test.ts`.
+- `./package.json` export; `CHANGELOG.md` (this file).
+
+## 0.9.0 — 2026-07-03
+
+- Full tokenization: zero raw color literals in `styles.css`; alpha tints
+  derived from semantic tokens via `color-mix()`; guard tests enforce it.
+- Official `night` theme (`[data-game-ui-theme='night']`).
+- Panel system: `GameCollapsiblePanel`, `GameWindowPanel`, `GameModal`
+  (native `<dialog>`: free focus trap, Esc, top layer).
+- All component CSS wrapped in `@layer swimmer-ui` — unlayered consumer
+  CSS always wins overrides.
+- A11y: tabs keyboard navigation (roving tabindex), unified focus ring,
+  tooltip focus/`:focus-within` support, themed scrollbars/selection.
+- Docs: `design-system-guide.md`, `usage-and-upgrade-playbook.md`.
+
+## 0.8.0 and earlier
+
+Extraction from TuringPact into a standalone package; OwnMySpace surface
+pack; terrain/build tooling; AI contractor queue; first-session shell;
+GitHub Packages publish workflow. See git history.

package/LICENSE

@@ -0,0 +1,41 @@
+PieAI Limited Use License 1.0
+
+Copyright (c) 2026 PieAI. All rights reserved.
+
+Subject to the restrictions below, PieAI grants you a limited,
+non-exclusive, non-transferable, revocable license to:
+
+1. download and install this package;
+2. read the source code for evaluation and integration purposes;
+3. use the unmodified package as a dependency in your applications; and
+4. perform ordinary build-time transformations, including bundling,
+   transpilation, tree-shaking, and minification, solely to include the
+   package in an application.
+
+You may not:
+
+1. modify or create derivative works from the source code or visual assets;
+2. redistribute, sublicense, publish, sell, or provide this package or its
+   visual assets as a standalone library, asset pack, template, or competing
+   product;
+3. extract or redistribute the visual assets separately from an application
+   that uses this package;
+4. remove or alter copyright, license, attribution, or proprietary notices;
+   or
+5. use PieAI names, logos, or trademarks to imply endorsement.
+
+Distribution of bundled or minified application output is permitted only when
+this package is an inseparable dependency of that application and is not
+offered as a reusable library or asset collection.
+
+This license does not grant ownership of any source code, visual asset,
+trademark, or other intellectual property. Third-party materials, if any,
+remain subject to their respective rights and terms.
+
+THE SOFTWARE AND ASSETS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+PIEAI WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
+FROM THE SOFTWARE, ASSETS, OR THEIR USE.
+
+Any use outside these terms requires prior written permission from PieAI.

package/README.md

@@ -0,0 +1,114 @@
+# @pieai/swimmer-ui-kit
+
+Self-contained clay game UI kit for PieAI web, game, and wrapped
+(mobile/desktop WebView) surfaces. React 19 + TypeScript strict.
+**Zero runtime dependencies, 100% standard CSS** — consumers need no
+Tailwind, no PostCSS, no CSS processor of any kind.
+
+Source is publicly readable. Use is governed by the
+[PieAI Limited Use License](./LICENSE), not an open-source license. The visual
+assets may not be extracted, modified, or redistributed as a standalone pack.
+
+- Design system truth (tokens, theming, motion, a11y):
+  `docs/reference/design-system-guide.md`
+- Consumer onboarding / upgrade SOP / release checklist:
+  `docs/reference/usage-and-upgrade-playbook.md`
+- Live catalog: `pnpm dev` (preview page) and `pnpm storybook`
+
+## Install
+
+```json
+{
+  "dependencies": {
+    "@pieai/swimmer-ui-kit": "1.0.0"
+  }
+}
+```
+
+Peer dependencies: `react >=19` and `react-dom >=19` — nothing else.
+Pin the exact version (no `^`) — upgrades are explicit, reviewed actions.
+The package is ESM-only and published publicly on npmjs. It uses the default
+npm registry, so consumers need no scope-specific `.npmrc` and no package-read
+token.
+
+Import the stylesheet once in the app shell:
+
+```ts
+import '@pieai/swimmer-ui-kit/styles.css';
+```
+
+**Optional** — only if the host app uses Tailwind v4 and wants Tailwind
+theme names (`bg-primary`, `text-foreground`, `rounded-md`…) to resolve to
+kit tokens, additionally import the bridge (requires the host's Tailwind
+build; never import it without Tailwind):
+
+```ts
+import '@pieai/swimmer-ui-kit/tailwind.css';
+```
+
+## What's inside
+
+- **~60 components** across: core controls (`GameButton`, `GameTabs`,
+  `GameSlider`, `GameToggle`, `GameForms` inputs…), panels and windows
+  (`GamePanel`, `GameCollapsiblePanel`, `GameWindowPanel`, `GameModal` on
+  native `<dialog>`), HUD/shell surfaces (`GameShell`, `GameHud`,
+  `GameSceneHudLayout`, `GameMovementPad`…), the OwnMySpace surface pack,
+  terrain/build tooling (`GameTerrainBuildToolbox`…), and the AI
+  contractor queue (`GameContractorPanel`…). `src/index.ts` is the
+  authoritative export list; Storybook is the visual catalog.
+- **Design tokens** as CSS variables (`--game-ui-*`) with TypeScript
+  mirrors (`CLAY_*_TOKENS`, `GAME_UI_TOKENS`). The CSS variables are the
+  cross-stack contract and work outside React:
+
+  ```css
+  .my-game-panel {
+    background: var(--game-ui-panel);
+    color: var(--game-ui-text);
+    border-radius: var(--game-ui-radius-panel);
+  }
+  ```
+
+- **Official themes**: light (default) and `night`
+  (`<html data-game-ui-theme="night">`). Downstream theming = overriding
+  semantic tokens; see the design system guide.
+- **Clay assets**: inline SVG mode by default (no asset hosting needed);
+  `setClayAssetMode('source')` switches to the sculpted PNG set, which
+  ships in `dist/assets/` for hosts to copy under
+  `/assets/game/ui/clay/…`.
+- **Audio helper**: `playGameInteractionSound` (SSR-safe, opt-in via the
+  `sound` prop on `GameButton`).
+
+## Wrapped-app (Capacitor/Tauri) readiness
+
+The kit treats WebView shells as first-class: interactive controls ship
+`touch-action: manipulation` and transparent tap highlights, hover-only
+affordances sit behind `@media (hover: hover)`, and every safe-area read
+flows through the `--game-ui-safe-*` tokens so hosts (e.g. Capacitor
+Android edge-to-edge, where raw `env(safe-area-inset-*)` can read 0) can
+override the source values in one place.
+
+## Compatibility contract (1.0)
+
+- Exported components and props, `.game-ui-*` class names, and
+  `--game-ui-*` token names are public API: additive-only within a major.
+- `dist/styles.css` stays 100% standard CSS (guard-tested; the CSS build
+  fails on any lightningcss warning).
+- Packaging is machine-checked: `publint` and `arethetypeswrong` run clean
+  (ESM-only by design — CJS consumers on Node ≥22 can `require(esm)` or
+  dynamic-import).
+
+See `CHANGELOG.md` for release history and migration notes.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev              # preview page (token ledger + all surfaces)
+pnpm storybook        # component catalog
+pnpm typecheck && pnpm test && pnpm build && pnpm docs:check
+```
+
+Releases use GitHub Actions Trusted Publishing: bump `package.json`, commit and
+push `main`, then run `gh workflow run npm-publish.yml --ref main`. The manual
+workflow is the release safety switch; it publishes to npmjs with short-lived
+OIDC credentials and provenance, without a local login or stored npm token.