@simhub2/justflipit 3.2.2 → 4.0.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 4.0.1
+
+- Enable 3D tilt on touch and reset it when the finger lifts or scrolling takes over.
+- Keep tap-to-flip active across flip, fade and scale without immediately flipping back on touch release.
+- Restrict axis rotation to the flip effect so fade also works with `FlipX: true`.
+
+## 4.0.0
+
+- One SSR-safe, dependency-free core with real ESM/CommonJS/browser exports.
+- Preserve original DOM nodes and event handlers; idempotent initialization and teardown.
+- Responsive grid faces, reversible transform transitions, fade and scale effects.
+- Frame-batched pointer tilt, touch tap, keyboard controls, inert hidden faces and live reduced motion.
+- Typed flip/toggle/update/state methods and change events.
+- React hook, Vue 3 directive and Svelte action using existing framework-owned faces.
+- Model-independent agent tool schema and allowlisted command executor with plain-text content.
+- Reproducible build, automated lifecycle tests, type checks, CI and npm release workflow.
+
+Breaking: jQuery registration removed; generated face classes replaced by data attributes;
+framework integrations use existing direct-child faces; npm exports now distinguish ESM and CJS.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) SimHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,145 +1,312 @@
-[![GitHub stars](https://img.shields.io/github/stars/SimHub/justFlipIt.svg?style=social)](https://github.com/SimHub/justFlipIt)
-[![npm version](https://img.shields.io/npm/v/@simhub2/justflipit.svg)](https://www.npmjs.com/package/@simhub2/justflipit)
-[![npm downloads](https://img.shields.io/npm/dt/@simhub2/justflipit.svg)](https://www.npmjs.com/package/@simhub2/justflipit)
-
-# justFlipIt
-
-A lightweight JavaScript library for beautiful, customizable flip and tilt animations on any DOM element.
+<p align="center">
+  <img src="img/readme-banner.svg" alt="justFlipIt v4 — A little motion. A new perspective." width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@simhub2/justflipit"><img src="https://img.shields.io/npm/v/%40simhub2%2Fjustflipit?style=flat-square&amp;color=b4df83" alt="npm version"></a>
+  <a href="https://github.com/SimHub/justFlipIt/actions/workflows/ci.yml"><img src="https://github.com/SimHub/justFlipIt/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-d9ccff?style=flat-square" alt="MIT license"></a>
+  <a href="#frameworks"><img src="https://img.shields.io/badge/TypeScript-included-93c5fd?style=flat-square" alt="TypeScript declarations included"></a>
+</p>
+
+<p align="center">
+  Responsive flip and tilt animations for your UI.<br>
+  One dependency-free core. Native framework lifecycles. Model-independent agent tools.
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#frameworks">React / Vue / Svelte</a> ·
+  <a href="#agent-tools">Agent tools</a> ·
+  <a href="#options">Options</a> ·
+  <a href="#upgrading-from-v3">Upgrade from v3</a>
+</p>
 
 ---
 
-### 🚀 [Live Demo & Examples](https://SimHub.github.io/justFlipIt/)
+## A card with more to say
 
-> **Try it out!**  
-> The interactive [Live Demo](https://SimHub.github.io/justFlipIt/) shows all features and use cases.
+Build product cards, reveal details, or let an agent control a card through explicit tool calls. Choose a 3D flip, a soft fade, or a scale transition, then add pointer-driven tilt.
 
----
+![justFlipIt demo showing flip cards, effect controls and an agent tool](img/demo.png)
 
-### ✨ Features
+**[Browse the demo source →](example/index.html)** · Run locally with `npm run build` and `python3 -m http.server 4173`, then open [localhost:4173/example/](http://localhost:4173/example/).
 
--   **Plug & Play**: Automatically adopts classes and styles for seamless integration.
--   **3D Tilt Effect**: Adds an interactive 3D tilt effect on hover and touch.
--   **Lightweight & Fast**: Minimal footprint, maximum performance.
--   **Highly Customizable**: Use your own styles, templates, and animations.
--   **Modern & Responsive**: Works on all modern browsers and devices.
--   **Flexible**: Use via CDN, NPM, or ES modules.
+| Motion that responds | Fits your application | Control when you need it |
+|---|---|---|
+| Flip on either axis, fade, and scale | React hook, Vue directive, Svelte action | `flip`, `toggle`, `update`, and state inspection |
+| Pointer tilt batched per animation frame | Existing framework-owned faces stay in place | Model-independent JSON-schema tool definition |
+| Touch, keyboard, and reduced-motion support | Responsive layout and SSR-safe imports | Typed API and change events |
 
----
+## Quick start
+
+```sh
+npm install @simhub2/justflipit
+```
 
-### 📦 Installation
+Add a container to your page, then initialize it after the element exists:
 
-**CDN / Local:**
 ```html
-<script src="https://unpkg.com/@simhub2/justflipit/dist/justFlipIt-modern.min.js"></script>
+<div class="product-card">
+  <h2>A different perspective</h2>
+  <p>Click to discover the other side.</p>
+</div>
 ```
 
-**NPM:**
-```bash
-npm install @simhub2/justflipit
-```
 ```js
-import justFlipIt from "@simhub2/justflipit";
+import justFlipIt from '@simhub2/justflipit';
+
+const card = justFlipIt(document.querySelector('.product-card'), {
+  Click: true,
+  Template: '<h2>There is more to see.</h2><p>Your details go here.</p>',
+  Tilt: { max: 10, perspective: 1000, scale: 1.03 },
+  Duration: 450,
+});
 ```
 
----
+The original node and its event listeners are preserved. Both faces participate in a responsive grid, so the card adapts to its content. Style the faces to match your design; the core supplies the motion and layout.
 
-### ▶️ Usage
+> `Template` accepts trusted application HTML. Use the agent bridge's `setText` action for model-generated text. With a framework, render content through the framework instead.
 
-Initialize the flip effect on your elements. The default trigger is **hover**.
+<details>
+<summary><strong>Using a browser script or CommonJS?</strong></summary>
 
-**Hover to Flip (Default)**
-```html
-<div class="card">Hover me!</div>
+**Browser script — no bundler:**
 
+```html
+<div class="card">Front of the card</div>
+<script src="https://cdn.jsdelivr.net/npm/@simhub2/justflipit@4.0.1/dist/justFlipIt.min.js"></script>
 <script>
-  justFlipIt('.card');
+  justFlipIt('.card', { Click: true, Template: '<p>Back of the card</p>' });
 </script>
 ```
 
-**Click to Flip**
+**CommonJS:**
+
 ```js
-justFlipIt('.card', { Click: true });
+const justFlipIt = require('@simhub2/justflipit');
+```
+
+The browser bundle exposes `window.justFlipIt`. ESM and CommonJS imports include matching TypeScript declarations.
+
+</details>
+
+## Frameworks
+
+Use two direct child elements as the front and back faces. The adapters attach behavior to those existing nodes, so reactive content remains owned by your framework.
+
+| Framework | Import | Integration | Cleanup |
+|---|---|---|---|
+| React 18+ | `@simhub2/justflipit/react` | `useFlip()` hook | Effect cleanup; StrictMode compatible |
+| Vue 3 | `@simhub2/justflipit/vue` | `vFlip` directive | `beforeUnmount` |
+| Svelte 4/5 | `@simhub2/justflipit/svelte` | `flip` action | Action `destroy()` |
+| Other frameworks | `@simhub2/justflipit` | Core with `Faces` selectors | Call `destroy()` before unmount |
+
+<details open>
+<summary><strong>React</strong> — hook, ref and controller</summary>
+
+```jsx
+import { useFlip } from '@simhub2/justflipit/react';
+
+export function ProductCard({ title, details }) {
+  const { ref, controller } = useFlip({ Click: true, Tilt: true });
+
+  return (
+    <section>
+      <div ref={ref}>
+        <div data-flip-front>{title}</div>
+        <div data-flip-back>{details}</div>
+      </div>
+      <button onClick={() => controller.current?.toggle()}>Flip card</button>
+    </section>
+  );
+}
+```
+
+In Next.js App Router, put this hook in a Client Component with `'use client'`.
+
+</details>
+
+<details>
+<summary><strong>Vue 3</strong> — directive with reactive options</summary>
+
+```vue
+<script setup>
+import { vFlip } from '@simhub2/justflipit/vue';
+
+defineProps({ title: String, details: String });
+</script>
+
+<template>
+  <div v-flip="{ Click: true, Effect: 'scale' }">
+    <div data-flip-front>{{ title }}</div>
+    <div data-flip-back>{{ details }}</div>
+  </div>
+</template>
+```
+
+</details>
+
+<details>
+<summary><strong>Svelte</strong> — action with lifecycle updates</summary>
+
+```svelte
+<script>
+  import { flip } from '@simhub2/justflipit/svelte';
+</script>
+
+<div use:flip={{ Click: true, Tilt: true }}>
+  <div data-flip-front>Front</div>
+  <div data-flip-back>Details</div>
+</div>
 ```
 
-**Enable Tilt Effect**
+</details>
+
+**Lifecycle notes:** Imports are safe during server rendering; initialize DOM controllers on the client. Keep `Faces` selectors stable while mounted. Render framework content through application state and omit `Template`. Avoid simultaneously managing the plugin's style, class and accessibility attributes from your framework.
+
+## Agent tools
+
+Connect any agent runtime that supports tool calls. Register the cards your agent may control, supply the exported schema to your runtime, and pass parsed tool arguments to the executor.
+
 ```js
-// Enable with default settings
-justFlipIt('.card', { tilt: true });
-
-// Customize tilt
-justFlipIt('.card', { 
-  tilt: {
-    max: 15,
-    perspective: 800
-  } 
+import justFlipIt from '@simhub2/justflipit';
+import { createAgentBridge } from '@simhub2/justflipit/agent';
+
+const product = justFlipIt(document.querySelector('.product-card'), {
+  Click: true,
 });
+const bridge = createAgentBridge({ product });
+
+// Wrap this definition in the tool format expected by your agent runtime.
+const tool = bridge.tool;
+
+// Execute the parsed arguments from a tool call.
+bridge.execute({ id: 'product', action: 'setText', text: 'Selected for you.' });
+const result = bridge.execute({ id: 'product', action: 'flip' });
+// { id: 'product', flipped: true, destroyed: false, effect: 'flip' }
 ```
 
----
+| Action | Result |
+|---|---|
+| `state` | Read the card's current state |
+| `flip` | Show the back |
+| `reset` | Show the front |
+| `toggle` | Switch sides |
+| `setText` | Replace the generated back face with plain text |
 
-### ⚙️ Options
+The bridge validates commands and accepts only registered card IDs. `setText` uses `textContent`, accepts up to 100,000 characters, and rejects framework-managed cards; update framework content through application state.
 
-Customize the behavior with these options.
+The executor runs in the browser alongside the DOM. Relay server-side tool calls through your application. The package provides a schema and executor; your application supplies the agent runtime and any model credentials.
 
-| Option          | Type    | Default  | Description                                                 |
-| --------------- | ------- | -------- | ----------------------------------------------------------- |
-| `tilt`          | Boolean / Object | `false`  | Enables a 3D tilt effect. Customize with `{ max, perspective }`. |
-| `Click`         | Boolean / String | `false`  | `true` for click trigger, or a selector for a custom trigger. |
-| `FlipX`         | Boolean | `false`  | `true` for vertical flip (around X-axis).                   |
-| `Template`      | String  | `null`   | HTML content for the back side.                             |
-| `preserveClasses` | Boolean | `true`   | Inherit all CSS classes from the original element.          |
-| `preserveStyles`| Boolean | `true`   | Inherit all inline styles from the original element.        |
-| `Duration`      | Number  | `400`    | Animation duration in ms.                                   |
-| `Easing`        | String  | `ease-in-out` | CSS easing function for the animation.                 |
-| `Style`         | Array   | `[]`     | Apply custom styles to the flip panels (see demo).          |
+## Controller API
 
+```js
+card.flip();                          // Show back
+card.flip(false);                     // Show front
+card.toggle();                        // Switch sides
+card.update({ Effect: 'fade' });       // Change options in place
+card.getState();                       // { flipped, destroyed, effect }
+card.destroy();                        // Remove listeners and restore the element
+```
+
+| Call | Returns |
+|---|---|
+| `justFlipIt(element, options)` | One controller |
+| `justFlipIt(selectorOrCollection, options)` | An array of controllers |
+| `justFlipIt.get(element)` | Existing controller, or `undefined` |
+| `justFlipIt.destroy(target)` | Destroys matching instances |
+
+Repeated initialization returns the existing instance. Use `update()` to change its options. `destroy()` is safe to call more than once. Initialize an HTML container, such as a `div`, rather than a void element such as `img`.
+
+```js
+card.hoverPanel.addEventListener('justflipit:change', ({ detail }) => {
+  console.log(detail.flipped, detail.effect);
+});
+```
+
+## Options
+
+| Option | Default | What it controls |
+|---|---|---|
+| `Click` | `false` | Hover by default; `true` for click; a selector or selector array for delegated clicks |
+| `FlipX` | `false` | X-axis rotation instead of Y-axis |
+| `Template` | Clone of original | Trusted HTML for a generated back face |
+| `Duration` | `400` | Non-negative duration in milliseconds |
+| `Easing` | `cubic-bezier(.22,.61,.36,1)` | CSS easing function |
+| `Effect` | `'flip'` | `'flip'`, `'fade'`, or `'scale'` |
+| `Tilt` | `false` | `true`, `'only'`, or `{ max, perspective, scale }` |
+| `ReducedMotion` | `true` | Respect live `prefers-reduced-motion` preferences |
+| `Faces` | Omitted | Existing direct children: `{ front: selector, back: selector }` |
+| `preserveClasses` | `true` | Copy original classes onto a generated container |
+| `preserveStyles` | `true` | Copy original inline styles onto a generated container |
+| `Style` | `[]` | Apply `{ el: 'self' or selector, style: {...} }` entries |
 
 <details>
-<summary><b>Advanced Example</b></summary>
+<summary><strong>Style existing faces and choose a different effect</strong></summary>
 
 ```js
-justFlipIt(".card", {
-  preserveClasses: false, // Start with a clean slate
+justFlipIt(document.querySelector('.card'), {
+  Faces: { front: '[data-front]', back: '[data-back]' },
   Click: true,
   FlipX: true,
-  tilt: true,
-  Duration: 800,
-  Easing: "cubic-bezier(0.68, -0.55, 0.27, 1.55)",
-  Template: "<div>My custom back side!</div>",
+  Effect: 'scale',
+  Duration: 500,
   Style: [
-    {
-      el: "self",
-      style: {
-        background: "#fff",
-        borderRadius: "1rem",
-        boxShadow: "0 2px 8px #0002",
-      },
-    },
-    { el: ".front", style: { background: "#f5c939", color: "#222" } },
-    { el: ".backY", style: { background: "#ca9dfe", color: "#fff" } },
+    { el: '[data-front]', style: { background: '#243b2b', borderRadius: '20px' } },
+    { el: '[data-back]', style: { background: '#c1f384', borderRadius: '20px' } },
   ],
 });
 ```
+
 </details>
 
----
+## Motion and accessibility
 
-### Versions & Compatibility
+- **Reversible transitions:** Rapid input reverses the current CSS transition without accumulating animation objects.
+- **Efficient tilt.** Mouse and finger movement share one animation frame. With `Tilt: true` or custom tilt settings, touch tilts the card until release or until the browser takes over a scroll gesture.
+- **Keyboard:** Focus the card, then use Enter or Space to toggle and Escape to reset.
+- **Touch.** Tap to switch sides with any effect. Hover mode distinguishes a tap from a drag, and click mode uses the browser’s native click. Use `Tilt: 'only'` for touch tilt without tap-to-flip.
+- **Hidden faces:** The inactive face is inert and marked `aria-hidden`.
+- **Reduced motion:** System preference changes disable transitions and tilt automatically. Set `ReducedMotion: false` only when your application intentionally overrides this preference.
 
--   **modern**: `justFlipIt-modern.js` (Recommended, uses Web Animations API)
--   **vanilla**: `justFlipIt-vanilla.js` (CSS transitions only)
--   **combined**: `justFlipIt-combined.js` (Optional jQuery support)
+Targets modern browsers with CSS Grid, Pointer Events, and native `inert` support. Add application-level polyfills when targeting older browsers. SSR safety covers importing the package; DOM initialization requires a browser.
 
-**Browser Support:**
--   ✅ Chrome 60+
--   ✅ Firefox 55+
--   ✅ Safari 12+
--   ✅ Edge 79+
+## Upgrading from v3
 
----
+**v4 is a major release.** Check these changes before upgrading an existing integration:
 
-### License
+| v3 integration | v4 equivalent |
+|---|---|
+| UMD-only npm entry | Default ESM import or callable CommonJS export |
+| Optional jQuery plugin registration | Call `justFlipIt(...)` directly |
+| Separate modern / vanilla / combined implementations | One core; historical import paths and browser filenames remain aliases |
+| `.front` / `.backY` generated face selectors | `[data-jfi-face="front"]` / `[data-jfi-face="back"]` |
+| `._flipY_` / `._flip_` state classes | `[data-jfi-flipped="true"]` |
+| Fixed measured dimensions | Responsive grid; add explicit sizes in your design where needed |
+| Framework DOM replacement | Existing direct-child faces via an adapter or `Faces` |
 
-Released under the **[MIT License](https://opensource.org/licenses/MIT)**.
+Option names retain PascalCase. `Faces` cannot change after initialization. Teardown restores plugin-owned attributes to their initial values.
+
+See the [changelog](CHANGELOG.md) for the release overview.
+
+## Development
+
+Use Node.js 22 or newer.
+
+```sh
+npm ci
+npm run check          # Lifecycle tests and TypeScript consumer checks
+npm run build          # ESM, CommonJS, browser bundles, source maps, declarations
+npm pack --dry-run     # Inspect published files
+```
+
+Tests cover original node preservation, teardown, delegated events, agent command validation, reduced motion, tilt batching, React StrictMode, Vue updates, and a compiled Svelte 5 component.
+
+See the [release guide](https://github.com/SimHub/justFlipIt/blob/main/RELEASING.md) for the GitHub and npm steps.
+
+---
 
-You are free to use, modify, and distribute this project, even for commercial purposes. All that is required is to include the original copyright and license notice in any copy of the software/source.
+<p align="center">
+  Built by <a href="https://github.com/SimHub">SimHub</a> · <a href="LICENSE">MIT license</a> · <a href="https://github.com/SimHub/justFlipIt/issues">Report an issue</a> · <a href="https://www.buymeacoffee.com/simhub">Buy me a coffee</a>
+</p>

package/dist/agent.cjs

@@ -0,0 +1,63 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/agent.js
+var agent_exports = {};
+__export(agent_exports, {
+  createAgentBridge: () => createAgentBridge,
+  flipTool: () => flipTool
+});
+module.exports = __toCommonJS(agent_exports);
+var flipTool = {
+  name: "control_flip_card",
+  description: "Inspect or control a registered flip card. Content is plain text.",
+  parameters: { type: "object", properties: { id: { type: "string" }, action: { type: "string", enum: ["state", "flip", "reset", "toggle", "setText"] }, text: { type: "string" } }, required: ["id", "action"], additionalProperties: false }
+};
+function createAgentBridge(cards) {
+  const registry = new Map(Object.entries(cards));
+  return {
+    tool: flipTool,
+    execute(command) {
+      if (!command || typeof command !== "object" || Object.keys(command).some((key) => !["id", "action", "text"].includes(key))) throw new TypeError("Invalid command");
+      const card = registry.get(command.id);
+      if (!card || card.destroyed) throw new Error("Unknown or destroyed card");
+      switch (command.action) {
+        case "state":
+          break;
+        case "flip":
+          card.flip(true);
+          break;
+        case "reset":
+          card.flip(false);
+          break;
+        case "toggle":
+          card.toggle();
+          break;
+        case "setText":
+          if (card.managed) throw new Error("Update framework content through application state");
+          if (typeof command.text !== "string" || command.text.length > 1e5) throw new TypeError("Expected text up to 100000 characters");
+          card.backWrapper.textContent = command.text;
+          break;
+        default:
+          throw new TypeError("Unknown action");
+      }
+      return { id: command.id, ...card.getState() };
+    }
+  };
+}
+//# sourceMappingURL=agent.cjs.map

package/dist/agent.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/adapters/agent.js"],
+  "sourcesContent": ["export const flipTool = {\n  name: 'control_flip_card',\n  description: 'Inspect or control a registered flip card. Content is plain text.',\n  parameters: { type: 'object', properties: { id: { type: 'string' }, action: { type: 'string', enum: ['state', 'flip', 'reset', 'toggle', 'setText'] }, text: { type: 'string' } }, required: ['id', 'action'], additionalProperties: false }\n};\nexport function createAgentBridge(cards) {\n  const registry = new Map(Object.entries(cards));\n  return {\n    tool: flipTool,\n    execute(command) {\n      if (!command || typeof command !== 'object' || Object.keys(command).some(key => !['id', 'action', 'text'].includes(key))) throw new TypeError('Invalid command');\n      const card = registry.get(command.id);\n      if (!card || card.destroyed) throw new Error('Unknown or destroyed card');\n      switch (command.action) {\n        case 'state': break;\n        case 'flip': card.flip(true); break;\n        case 'reset': card.flip(false); break;\n        case 'toggle': card.toggle(); break;\n        case 'setText':\n          if (card.managed) throw new Error('Update framework content through application state');\n          if (typeof command.text !== 'string' || command.text.length > 100000) throw new TypeError('Expected text up to 100000 characters');\n          card.backWrapper.textContent = command.text; break;\n        default: throw new TypeError('Unknown action');\n      }\n      return { id: command.id, ...card.getState() };\n    }\n  };\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,WAAW;AAAA,EACtB,MAAM;AAAA,EACN,aAAa;AAAA,EACb,YAAY,EAAE,MAAM,UAAU,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,GAAG,QAAQ,EAAE,MAAM,UAAU,MAAM,CAAC,SAAS,QAAQ,SAAS,UAAU,SAAS,EAAE,GAAG,MAAM,EAAE,MAAM,SAAS,EAAE,GAAG,UAAU,CAAC,MAAM,QAAQ,GAAG,sBAAsB,MAAM;AAC7O;AACO,SAAS,kBAAkB,OAAO;AACvC,QAAM,WAAW,IAAI,IAAI,OAAO,QAAQ,KAAK,CAAC;AAC9C,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,SAAS;AACf,UAAI,CAAC,WAAW,OAAO,YAAY,YAAY,OAAO,KAAK,OAAO,EAAE,KAAK,SAAO,CAAC,CAAC,MAAM,UAAU,MAAM,EAAE,SAAS,GAAG,CAAC,EAAG,OAAM,IAAI,UAAU,iBAAiB;AAC/J,YAAM,OAAO,SAAS,IAAI,QAAQ,EAAE;AACpC,UAAI,CAAC,QAAQ,KAAK,UAAW,OAAM,IAAI,MAAM,2BAA2B;AACxE,cAAQ,QAAQ,QAAQ;AAAA,QACtB,KAAK;AAAS;AAAA,QACd,KAAK;AAAQ,eAAK,KAAK,IAAI;AAAG;AAAA,QAC9B,KAAK;AAAS,eAAK,KAAK,KAAK;AAAG;AAAA,QAChC,KAAK;AAAU,eAAK,OAAO;AAAG;AAAA,QAC9B,KAAK;AACH,cAAI,KAAK,QAAS,OAAM,IAAI,MAAM,oDAAoD;AACtF,cAAI,OAAO,QAAQ,SAAS,YAAY,QAAQ,KAAK,SAAS,IAAQ,OAAM,IAAI,UAAU,uCAAuC;AACjI,eAAK,YAAY,cAAc,QAAQ;AAAM;AAAA,QAC/C;AAAS,gBAAM,IAAI,UAAU,gBAAgB;AAAA,MAC/C;AACA,aAAO,EAAE,IAAI,QAAQ,IAAI,GAAG,KAAK,SAAS,EAAE;AAAA,IAC9C;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/agent.d.cts

@@ -0,0 +1,4 @@
+import type { FlipController, FlipState } from './justFlipIt.mjs';
+export interface AgentCommand { id: string; action: 'state' | 'flip' | 'reset' | 'toggle' | 'setText'; text?: string }
+export const flipTool: { name: string; description: string; parameters: Record<string, unknown> };
+export function createAgentBridge(cards: Record<string, FlipController>): { tool: typeof flipTool; execute(command: AgentCommand): FlipState & { id: string } };

package/dist/agent.d.mts

@@ -0,0 +1,4 @@
+import type { FlipController, FlipState } from './justFlipIt.mjs';
+export interface AgentCommand { id: string; action: 'state' | 'flip' | 'reset' | 'toggle' | 'setText'; text?: string }
+export const flipTool: { name: string; description: string; parameters: Record<string, unknown> };
+export function createAgentBridge(cards: Record<string, FlipController>): { tool: typeof flipTool; execute(command: AgentCommand): FlipState & { id: string } };

package/dist/agent.d.ts

@@ -0,0 +1,4 @@
+import type { FlipController, FlipState } from './justFlipIt';
+export interface AgentCommand { id: string; action: 'state' | 'flip' | 'reset' | 'toggle' | 'setText'; text?: string }
+export const flipTool: { name: string; description: string; parameters: Record<string, unknown> };
+export function createAgentBridge(cards: Record<string, FlipController>): { tool: typeof flipTool; execute(command: AgentCommand): FlipState & { id: string } };

package/dist/agent.mjs

@@ -0,0 +1,43 @@
+// src/adapters/agent.js
+var flipTool = {
+  name: "control_flip_card",
+  description: "Inspect or control a registered flip card. Content is plain text.",
+  parameters: { type: "object", properties: { id: { type: "string" }, action: { type: "string", enum: ["state", "flip", "reset", "toggle", "setText"] }, text: { type: "string" } }, required: ["id", "action"], additionalProperties: false }
+};
+function createAgentBridge(cards) {
+  const registry = new Map(Object.entries(cards));
+  return {
+    tool: flipTool,
+    execute(command) {
+      if (!command || typeof command !== "object" || Object.keys(command).some((key) => !["id", "action", "text"].includes(key))) throw new TypeError("Invalid command");
+      const card = registry.get(command.id);
+      if (!card || card.destroyed) throw new Error("Unknown or destroyed card");
+      switch (command.action) {
+        case "state":
+          break;
+        case "flip":
+          card.flip(true);
+          break;
+        case "reset":
+          card.flip(false);
+          break;
+        case "toggle":
+          card.toggle();
+          break;
+        case "setText":
+          if (card.managed) throw new Error("Update framework content through application state");
+          if (typeof command.text !== "string" || command.text.length > 1e5) throw new TypeError("Expected text up to 100000 characters");
+          card.backWrapper.textContent = command.text;
+          break;
+        default:
+          throw new TypeError("Unknown action");
+      }
+      return { id: command.id, ...card.getState() };
+    }
+  };
+}
+export {
+  createAgentBridge,
+  flipTool
+};
+//# sourceMappingURL=agent.mjs.map

package/dist/agent.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/adapters/agent.js"],
+  "sourcesContent": ["export const flipTool = {\n  name: 'control_flip_card',\n  description: 'Inspect or control a registered flip card. Content is plain text.',\n  parameters: { type: 'object', properties: { id: { type: 'string' }, action: { type: 'string', enum: ['state', 'flip', 'reset', 'toggle', 'setText'] }, text: { type: 'string' } }, required: ['id', 'action'], additionalProperties: false }\n};\nexport function createAgentBridge(cards) {\n  const registry = new Map(Object.entries(cards));\n  return {\n    tool: flipTool,\n    execute(command) {\n      if (!command || typeof command !== 'object' || Object.keys(command).some(key => !['id', 'action', 'text'].includes(key))) throw new TypeError('Invalid command');\n      const card = registry.get(command.id);\n      if (!card || card.destroyed) throw new Error('Unknown or destroyed card');\n      switch (command.action) {\n        case 'state': break;\n        case 'flip': card.flip(true); break;\n        case 'reset': card.flip(false); break;\n        case 'toggle': card.toggle(); break;\n        case 'setText':\n          if (card.managed) throw new Error('Update framework content through application state');\n          if (typeof command.text !== 'string' || command.text.length > 100000) throw new TypeError('Expected text up to 100000 characters');\n          card.backWrapper.textContent = command.text; break;\n        default: throw new TypeError('Unknown action');\n      }\n      return { id: command.id, ...card.getState() };\n    }\n  };\n}\n"],
+  "mappings": ";AAAO,IAAM,WAAW;AAAA,EACtB,MAAM;AAAA,EACN,aAAa;AAAA,EACb,YAAY,EAAE,MAAM,UAAU,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,GAAG,QAAQ,EAAE,MAAM,UAAU,MAAM,CAAC,SAAS,QAAQ,SAAS,UAAU,SAAS,EAAE,GAAG,MAAM,EAAE,MAAM,SAAS,EAAE,GAAG,UAAU,CAAC,MAAM,QAAQ,GAAG,sBAAsB,MAAM;AAC7O;AACO,SAAS,kBAAkB,OAAO;AACvC,QAAM,WAAW,IAAI,IAAI,OAAO,QAAQ,KAAK,CAAC;AAC9C,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,SAAS;AACf,UAAI,CAAC,WAAW,OAAO,YAAY,YAAY,OAAO,KAAK,OAAO,EAAE,KAAK,SAAO,CAAC,CAAC,MAAM,UAAU,MAAM,EAAE,SAAS,GAAG,CAAC,EAAG,OAAM,IAAI,UAAU,iBAAiB;AAC/J,YAAM,OAAO,SAAS,IAAI,QAAQ,EAAE;AACpC,UAAI,CAAC,QAAQ,KAAK,UAAW,OAAM,IAAI,MAAM,2BAA2B;AACxE,cAAQ,QAAQ,QAAQ;AAAA,QACtB,KAAK;AAAS;AAAA,QACd,KAAK;AAAQ,eAAK,KAAK,IAAI;AAAG;AAAA,QAC9B,KAAK;AAAS,eAAK,KAAK,KAAK;AAAG;AAAA,QAChC,KAAK;AAAU,eAAK,OAAO;AAAG;AAAA,QAC9B,KAAK;AACH,cAAI,KAAK,QAAS,OAAM,IAAI,MAAM,oDAAoD;AACtF,cAAI,OAAO,QAAQ,SAAS,YAAY,QAAQ,KAAK,SAAS,IAAQ,OAAM,IAAI,UAAU,uCAAuC;AACjI,eAAK,YAAY,cAAc,QAAQ;AAAM;AAAA,QAC/C;AAAS,gBAAM,IAAI,UAAU,gBAAgB;AAAA,MAC/C;AACA,aAAO,EAAE,IAAI,QAAQ,IAAI,GAAG,KAAK,SAAS,EAAE;AAAA,IAC9C;AAAA,EACF;AACF;",
+  "names": []
+}