@fluritheme/moon-explorer 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First lunar expedition: articulated astronaut, thruster landing and egress, low-gravity surface exploration, rock sampling, persistent flags, rover boarding/driving/dismount, telescope observations, waves, naps and shooting stars. Document-space physics, responsive canvas, reduced-motion support, bounded particles, deterministic missions, typed controller and events.

package/LICENSE

@@ -0,0 +1,56 @@
+FLURI THEMES COMMERCIAL LICENSE 1.0
+Effective date: 14 November 2026
+Copyright (c) 2026 František Gejdoš. All rights reserved, except as granted below.
+Licensor: František Gejdoš, Slovakia, trading as Fluri Themes.
+Contact: fluritheme@gmail.com
+Canonical terms: https://fluri.xyz/license/
+
+1. Scope and acceptance
+
+This license covers Fluri Themes software, original theme artwork and accompanying documentation supplied with this license (the Software). It applies to the new commercial releases identified in LICENSING.md, and to future Fluri Themes releases supplied under these terms. Downloading a package does not by itself grant a production-use license. Rights in previously released MIT versions are preserved under section 6.
+
+2. Evaluation before purchase
+
+You may download, inspect, install and modify the Software solely for private, non-production evaluation on your own devices and access-restricted test environments. You may view and interact with Fluri's official public demonstrations. Evaluation does not permit production use, public deployment, client delivery, public source redistribution or commercial exploitation. A paid license is required for those production and client uses. Automated security analysis and package-registry processing are permitted.
+
+3. One purchase, lifetime access
+
+A valid purchase of the Fluri Themes Lifetime License grants the named buyer a non-exclusive, worldwide, perpetual license to use and modify all current and future Fluri Themes for unlimited personal, business and client websites and web applications. The listed one-time price is EUR 19; any legally required tax information and total payable must be provided before purchase. A receipt or written license confirmation from Fluri identifies the buyer and records the purchase. There are no recurring license fees and no per-project or per-domain charges.
+
+Lifetime means the right to continue using lawfully obtained themes does not expire while you comply with this license. The purchase also includes access to future Fluri themes and theme updates without another theme-license payment. You may retain your own backup copies. No particular release count, release date, support response time or perpetual operation of a hosting or download service is promised. Any mandatory obligations concerning updates, digital content and consumer remedies remain applicable.
+
+4. Personal and client projects
+
+The buyer may be an individual or a legal entity. Employees and contractors may work with the Software only on projects covered by that buyer's license and may not use shared access for their unrelated projects. The buyer remains responsible for providing access appropriately.
+
+You may bundle the Software, including reasonably necessary source code, into a completed website or application and charge clients for that completed project and your services. A client may operate, maintain and modify the delivered project without purchasing a separate Fluri license. That permission does not give the client a reusable theme-library license for unrelated projects. Ordinary browser delivery of compiled or bundled JavaScript, and project handover to the client or their maintainer, are permitted. Your finished project must provide substantial functionality or content beyond redistributing Fluri themes.
+
+5. Restrictions
+
+Except for the project delivery permitted in section 4, you may not sell, sublicense, give away, publicly redistribute or make the Software available as standalone themes, packages, downloadable source, a template pack, asset collection, theme marketplace or competing reusable library. You may not share purchase credentials or bulk-download access with unrelated buyers, or offer a service whose primary purpose is allowing others to extract, download or redistribute the themes. Private backups and private project repositories are allowed.
+
+You may customize themes for your own and client projects. You may not claim authorship of Fluri's unmodified original assets or imply endorsement by Fluri. Keep supplied copyright, license and third-party notices in source distributions and project handovers where applicable. No visible website credit or Fluri branding is required. Rights independently granted by a third party's license or a hosting platform's applicable terms are not restricted by this license.
+
+6. Existing MIT releases
+
+This license does not replace, revoke or restrict the MIT license attached to earlier published versions: @fluritheme/fluri through 0.2.1; @fluritheme/fluri-react through 0.2.1; @fluritheme/spider through 0.2.1; and @fluritheme/grinch through 0.1.1. Those releases and copies remain governed by their original MIT terms. The first commercial releases are Winter core and React adapter 0.3.0, Spider 0.3.0 and Grinch 0.2.0. New themes use this commercial license from their initial release unless Fluri expressly supplies another license. See LICENSE-MIT-LEGACY for the historical notice. This is not a choice of MIT or commercial licensing for the current commercial release.
+
+7. Third-party materials
+
+Dependencies, fonts, contributed material and other third-party components retain their own licenses and required notices. This license does not grant exclusive rights to third-party material or replace its terms. The Fluri name and brand are not licensed for use as your own brand. Your content and modifications remain yours, subject to the license obligations for any incorporated Fluri material.
+
+8. Operation and privacy
+
+The animation runtime does not require online license activation, insert an advertising watermark or send installation telemetry. You remain responsible for integrating it appropriately, preserving usable page controls and respecting visitor motion preferences. Compatibility and performance depend on the host website and device.
+
+9. Termination
+
+You may stop using the Software at any time. Fluri may terminate this license for a material breach that remains uncorrected for 30 days after written notice explaining the breach, where correction is possible. On termination you must stop creating new deployments and stop using or redistributing the affected Software, except to the extent mandatory law or independently granted rights provide otherwise. Termination does not revoke rights under the legacy MIT releases. A refund or reversed payment is handled under the applicable purchase terms and mandatory law; it does not silently alter third-party open-source rights.
+
+10. Warranty, liability and mandatory rights
+
+Except for express promises made at purchase and rights that cannot lawfully be excluded, the Software is supplied as is, without a promise of fitness for every website or uninterrupted operation. To the extent permitted by applicable law, Fluri is not liable for indirect or consequential losses arising from use of the Software. Nothing in this license excludes or limits liability, guarantees, withdrawal rights, digital-content remedies or other protections that cannot lawfully be excluded or limited, including applicable consumer rights. This license does not impose an automatic waiver of refund or withdrawal rights.
+
+11. Version of the agreement
+
+Keep this license with your purchase records. Later changes to Fluri's published license do not retroactively narrow rights already granted under this version. Any additional services or separately agreed support have their own clearly disclosed terms. Questions and license requests: fluritheme@gmail.com.

package/LICENSE-MIT-LEGACY

@@ -0,0 +1,23 @@
+Historical notice: this MIT license applies only to the legacy versions listed in LICENSING.md. It does not license the current commercial release.
+
+MIT License
+
+Copyright (c) 2026 Fluri contributors
+
+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/LICENSING.md

@@ -0,0 +1,22 @@
+# Fluri licensing
+
+Current and future commercial releases use [Fluri Themes Commercial License 1.0](https://fluri.xyz/license/), included in `LICENSE`. A EUR 19 one-time Lifetime License covers all current and future Fluri themes on unlimited personal, business and client websites. Finished client projects may be delivered; selling or publicly redistributing the themes as a reusable library or template pack is prohibited. Private non-production evaluation is permitted before purchase. The full license controls.
+
+| Package                   | Last MIT release | First commercial release |
+| ------------------------- | ---------------- | ------------------------ |
+| `@fluritheme/fluri`       | 0.2.1            | 0.3.0                    |
+| `@fluritheme/fluri-react` | 0.2.1            | 0.3.0                    |
+| `@fluritheme/spider`      | 0.2.1            | 0.3.0                    |
+| `@fluritheme/grinch`      | 0.1.1            | 0.2.0                    |
+
+The listed MIT releases remain MIT. No historical package, release tag or license grant is overwritten or revoked. `LICENSE-MIT-LEGACY` records the old notice; it does not grant an MIT option for current commercial releases. Third-party dependencies and fonts retain their own licenses.
+
+The public npm package is downloadable for inspection and private evaluation. A paid license is required before production deployment or client delivery. There is no runtime license check or telemetry. Contact fluritheme@gmail.com to arrange a license; an automated checkout and customer download portal are separate work and are not represented as complete.
+
+## New packages and release checks
+
+Copy `LICENSE`, `LICENSE-MIT-LEGACY`, `LICENSING.md` and `licensing.json` from the Fluri collection repository. Set package.json `license` to `SEE LICENSE IN LICENSE` and `homepage` to `https://fluri.xyz/`. Include the license and licensing notes in the archive. Copy scripts/check-licensing.mjs and invoke it from prepublishOnly so a new package cannot silently revert to MIT. Preserve third-party notices. New themes are commercial from version 0.1.0 unless the owner explicitly selects a free edition. Never infer an MIT license from an old package or scaffold.
+
+## Hosted platform transition — 15 November 2026
+
+The paragraphs above document the historical Commercial License 1.0 and published archives. They are not an invitation to buy the old €19 offer through the new preview. The hosted-platform source is a separate private project; its current checkout is simulation-only and grants no production access. New platform terms are under /legal/; legacy raw licences remain at /legacy/ and inside each archive. See docs/platform-launch-status.md before enabling any payments. Do not rewrite an old licence or assert that minification makes browser code unextractable.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# Moon Explorer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A small step. A whole little world.**
+
+A curious astronaut lands on your page, explores its edges, collects moon rocks, plants little flags and takes a pocket-sized rover for a drive. Drawn entirely in Canvas 2D, with articulated limbs, a reflective visor, soft dust, reactive eyes and properly unhurried lunar motion.
+
+[Explore Fluri](https://fluri.xyz/) · [Licence](https://fluri.xyz/legal/license/) · [Installation help](https://fluri.xyz/docs/)
+
+![Moon Explorer: astronaut, rover and lander exploring a real website](https://fluri.xyz/previews/moon-explorer.gif)
+
+[Watch the motion preview](https://fluri.xyz/previews/moon-explorer.mp4)
+
+## An expedition, not a looping sticker
+
+- **A real arrival:** throttled descent, landing dust, touchdown, ladder and astronaut egress.
+- **Low-gravity exploration:** walking, articulated steps, footprints, long arcs and soft landing reactions between actual page edges.
+- **Little discoveries:** crouch, geological hammer, sample collection, celebration and persistent mission counters.
+- **A flag of your own:** animated planting, tiny lunar crescent and bounded persistent flags.
+- **A proper rover:** boarding, moving suspension, spinning wheels, dish antenna, driving dust and dismounting.
+- **Personality:** curious eyes, blinking, waves, telescope observations, a moon nap and shooting stars.
+- **A considerate guest:** no click interception, no CSS import, no root restyling, reduced-motion support, bounded particles, offscreen pausing and cleanup.
+- **Typed control:** queue missions, target a surface, receive events, update options and inspect expedition telemetry.
+
+![Moon Explorer desktop preview](https://fluri.xyz/previews/moon-explorer-desktop.png)
+
+## Install
+
+```sh
+npm install @fluritheme/moon-explorer
+```
+
+```ts
+import { createMoonExplorer } from "@fluritheme/moon-explorer";
+
+const moon = createMoonExplorer({
+  surfaces: "[data-moon-surface]",
+  autoExplore: true,
+  rover: true,
+});
+
+// In your HTML: <article data-moon-surface>...</article>
+moon.collect();
+moon.plantFlag();
+moon.ride();
+
+// Always clean up when the page or component unmounts.
+moon.destroy();
+```
+
+Call the factory after your DOM has mounted. The default root is the full document; pass an element to keep the expedition inside a particular section. Importing the package in a server-rendered app does not access the DOM. A factory call without a browser returns an idle controller; create a fresh controller on the client to start the expedition.
+
+## React
+
+```tsx
+import { useEffect, useRef } from "react";
+import { createMoonExplorer } from "@fluritheme/moon-explorer";
+
+export function MoonSection() {
+  const root = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (!root.current) return;
+    const moon = createMoonExplorer({
+      root: root.current,
+      surfaces: "[data-moon-surface]",
+      accent: "#ef9459",
+    });
+    return () => moon.destroy();
+  }, []);
+
+  return (
+    <section ref={root}>
+      <article data-moon-surface>Your content still works.</article>
+    </section>
+  );
+}
+```
+
+The same lifecycle works in Vue `onMounted`/`onBeforeUnmount`, Svelte `onMount` or a normal script. No framework adapter is required.
+
+## Configuration
+
+| Option          | Default                                               | Purpose                                                                          |
+| --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `root`          | Document body                                         | Expedition territory. A scoped root is clipped without modifying its styles.     |
+| `surfaces`      | `[data-moon-surface], button, h1, h2, article, .card` | Upper edges to measure as landing and walking surfaces.                          |
+| `size`          | `1`                                                   | Character and equipment scale, clamped to `0.55–1.8`.                            |
+| `pace`          | `1`                                                   | Mission and movement speed, `0.3–2.5`.                                           |
+| `autoExplore`   | `true`                                                | Autonomously choose missions between idle moments.                               |
+| `interactive`   | `true`                                                | Look at nearby pointers and wave when clicked nearby. Page events remain usable. |
+| `rover`         | `true`                                                | Include the rover and enable driving missions.                                   |
+| `lander`        | `true`                                                | Draw the lander. Landing remains part of the arrival sequence.                   |
+| `shootingStars` | `true`                                                | Occasional decorative stars while the expedition runs.                           |
+| `maxFlags`      | `5`                                                   | Maximum retained flags, `0–12`. Oldest flags retire first.                       |
+| `accent`        | `#ef9459`                                             | Hex colour for suit, rover, lander and flags.                                    |
+| `seed`          | `42`                                                  | Seeded mission/layout variation.                                                 |
+| `maxFPS`        | `40`                                                  | Maximum drawing rate, `12–60`.                                                   |
+| `maxDPR`        | `1.5`                                                 | Rendering density cap, `1–2.5`.                                                  |
+| `zIndex`        | `30`                                                  | Overlay stacking level.                                                          |
+| `motion`        | `'respect'`                                           | Honour reduced motion; `'static'` always shows a still pose.                     |
+
+`surfaces`, `root` and `seed` are construction options. `update()` accepts the other options. Wide, stable surfaces look best: narrow or hidden elements are skipped. Fixed-position elements are excluded because they do not share the document’s coordinate system. Use explicit surface markers when automatic detection finds too many irrelevant objects.
+
+## Control the expedition
+
+```ts
+moon.explore("#next-card"); // Jump to a specific measured surface.
+moon.collect(); // Survey a rock and collect a sample.
+moon.plantFlag(); // Plant a flag and celebrate.
+moon.ride(); // Board, drive and dismount the rover.
+moon.observe(); // Raise a telescope and watch the sky.
+moon.jump(); // A little low-gravity leap.
+moon.wave();
+moon.rest();
+moon.shootingStar(); // Decorative effect, not a queued mission.
+moon.land("#landing-pad"); // Clear the queue and repeat arrival.
+
+moon.update({ pace: 1.3, autoExplore: false });
+moon.pause();
+moon.resume();
+moon.refresh(); // Re-measure after an unusual layout change.
+```
+
+Mission methods return `true` when queued and `false` when unavailable, the queue is full, the target selector is invalid, reduced motion is enabled or the controller is destroyed. Up to eight missions can wait. They run after the current mission, so a collecting astronaut finishes its sample before taking a rover ride. `land()` restarts the arrival instead. A star is drawn only while animation is permitted.
+
+```ts
+const unsubscribe = moon.on("sample", ({ samples, surface }) => {
+  console.log(`Sample ${samples} collected at ${surface}`);
+});
+
+console.log(moon.getState());
+unsubscribe();
+```
+
+Events: `phase`, `mission`, `sample`, `flag`, `landed`. The frozen snapshot includes lifecycle state, animation phase, current mission, document-space position, surface ID, sample count, flags, walking distance, rover distance, completed missions, elapsed simulation time and reduced-motion state. Event handlers are isolated so a thrown callback cannot stop the renderer.
+
+## Motion and performance
+
+The canvas is a transparent, pointer-inert overlay. The expedition is measured in **document CSS coordinates**; scrolling only changes the camera. Resize and DOM changes trigger bounded re-measurement. The runtime pauses when the tab is hidden or a scoped territory leaves the viewport. Reduced motion shows a still character and equipment without a landing or autonomous missions; no forced-motion bypass is provided.
+
+Dust, footprints, rocks, stars, flags and the mission queue all have caps. Rendering density and frame rate are bounded. This is a decorative animation, not a physics simulation for critical use. Test your own layout, performance budget, sticky content and Content Security Policy before production use.
+
+![Moon Explorer mobile preview](https://fluri.xyz/previews/moon-explorer-mobile.png)
+
+## Privacy and licensing
+
+This standalone npm runtime makes **no network requests**, sets no cookies, collects no visitor information, performs no online licence check and adds no watermark. Fluri’s separately hosted installer and optional website analytics have their own configuration and disclosures; installing this package alone does not enable them.
+
+Moon Explorer is supplied under the **Fluri Themes Commercial License**, included in `LICENSE`. Downloading the public package permits inspection and private, non-production evaluation under those terms; production and client use require an applicable licence. The current hosted platform offer and existing archive licences are distinct. Read the supplied licence and [current Fluri terms](https://fluri.xyz/legal/) rather than treating an npm download as a purchase. Historical MIT packages retain their original rights; Moon Explorer has not had an MIT release.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+pnpm dev
+pnpm previews
+```
+
+The preview generator records the actual running browser animation, then exports GIF, MP4 and desktop/mobile screenshots. Tests cover mission progression, single-count sample collection, limits, scroll stability, surface changes, reduced motion, host controls, disposal and browser errors.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { MoonExplorerOptions, MoonExplorerController } from "./types.js";
+export type * from "./types.js";
+/** Create a self-contained lunar expedition. Importing the module is SSR-safe. */
+export declare function createMoonExplorer(input?: MoonExplorerOptions): MoonExplorerController;