lostpage 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satender Maurya
+
+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,3 +1,391 @@
-# Temporary Holding Version
+# lostpage
 
-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.
+**Immersive 404 pages for every framework.** Live WebGL oceans, black holes, chrome and glass 3D type, playable arcade games, retro terminals, paper craft and more, each one a drop-in component.
+
+- **116 scenes, 650+ designs.** From plain, fast everyday pages (minimal, search, helpful links, card…) to immersive 3D. Every scene ships with presets: palettes, moods and copy.
+- **Any framework:** React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, Astro, Solid, plain HTML / CDN.
+- **Zero dependencies.** Each scene is 3–20 kB and code-split, so only the one you use is downloaded.
+- **Accessible:** real headings and links, `prefers-reduced-motion` support, and a text-only fallback when WebGL isn't available.
+- **Fully customisable:** copy, buttons, colours, fonts and scene parameters, or bring your own content on top.
+
+## Install
+
+```bash
+npm i lostpage
+# or
+pnpm add lostpage
+yarn add lostpage
+bun add lostpage
+```
+
+## Quick start
+
+### Next.js (App Router)
+
+```tsx
+// app/not-found.tsx
+import { LostPage } from "lostpage/react";
+
+export default function NotFound() {
+  return <LostPage scene="lost-at-sea" />;
+}
+```
+
+Pages Router: put the same component in `pages/404.tsx`.
+
+### React (Vite, Remix, Gatsby…)
+
+```tsx
+import { LostPage } from "lostpage/react";
+
+<Route path="*" element={<LostPage scene="black-hole" preset="quasar" />} />
+```
+
+### Vue 3 / Nuxt
+
+```vue
+<script setup lang="ts">
+import { LostPage } from "lostpage/vue";
+</script>
+
+<template>
+  <LostPage scene="chrome-404" preset="gold" />
+</template>
+```
+
+In Nuxt, use it inside `error.vue` (wrapped in `<ClientOnly>`) and pass `:code="String(error.statusCode)"`.
+
+### Svelte / SvelteKit
+
+```svelte
+<script>
+  import { lostpage } from "lostpage/svelte";
+</script>
+
+<div use:lostpage={{ scene: "terminal", preset: "green" }}></div>
+```
+
+### Angular, Astro, Solid, Lit, Qwik (Web Component)
+
+```ts
+import "lostpage/element";
+```
+
+```html
+<lost-page scene="rainy-window" preset="amber" heading="The café's shut."></lost-page>
+```
+
+In Angular, add `CUSTOM_ELEMENTS_SCHEMA` to the component.
+
+### Plain HTML / CDN
+
+```html
+<lost-page scene="lost-at-sea"></lost-page>
+<script type="module" src="https://cdn.jsdelivr.net/npm/lostpage/dist/cdn/element.js"></script>
+```
+
+Or the single-file classic script, which bundles every scene:
+
+```html
+<div id="nf"></div>
+<script src="https://cdn.jsdelivr.net/npm/lostpage/dist/lostpage.global.js"></script>
+<script>LostPage.mount("#nf", "pond", { preset: "night" });</script>
+```
+
+### Vanilla JavaScript
+
+```js
+import { mount } from "lostpage";
+
+const handle = mount(document.body, "nixie", { preset: "argon" });
+// handle.update({ title: "…" }); handle.pause(); handle.resume(); handle.destroy();
+```
+
+## CLI
+
+```bash
+npx lostpage list                   # every scene and preset
+npx lostpage list ocean             # filter by id, category or tag
+npx lostpage add black-hole:quasar  # writes the right file for your framework
+npx lostpage add terminal --framework sveltekit
+npx lostpage random
+```
+
+The framework is detected from your `package.json`: Next (app or pages router), Nuxt, SvelteKit, Svelte, Astro, Angular, Remix, Solid, Vue or React. Without one, the CLI writes a standalone `404.html`.
+
+## Customise
+
+All options work the same in every framework (props in React and Vue, the object in Svelte and `mount`, attributes on the web component).
+
+```tsx
+<LostPage
+  scene="lost-at-sea"
+  preset="storm"                       // pick a preset
+  code="410"                           // the status code shown
+  eyebrow="Small craft warning"
+  title="Rough waters."
+  message="This page didn't survive the storm."
+  actions={[
+    { label: "Head for harbour", href: "/" },
+    { label: "Contact us", href: "/contact", variant: "secondary" },
+  ]}
+  theme={{ accent: "#ff4d2e", "font-display": "Fraunces, serif" }}  // CSS variables
+  params={{ waveHeight: 1.4, rain: 1 }} // scene-specific knobs
+  height="100dvh"                      // or "100%" inside a sized parent
+  onNavigate={(href) => router.push(href)}
+/>
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `scene` | `string \| SceneDef` | Scene id (lazy-loaded) or a scene imported from `lostpage/scenes/<id>`. |
+| `preset` | `string` | One of the scene's presets. |
+| `code` | `string` | Status code shown. Default `"404"`. |
+| `eyebrow`, `title`, `message` | `string` | The copy. Falls back to the preset, then the scene. |
+| `actions` | `{ label, href?, onClick?, variant?, icon? }[]` | Buttons. `variant`: `primary` or `secondary`. |
+| `theme` | `Record<string, string>` | CSS variables without the `--lp-` prefix. |
+| `params` | `object` | Scene parameters (colours, speeds, counts…). |
+| `height` | `string` | CSS height. Default `100dvh`. |
+| `overlay` | `boolean` | Render the built-in text layer. Pass children to replace it. |
+| `motion` | `"auto" \| "reduce" \| "full"` | `auto` follows `prefers-reduced-motion`. |
+| `interactive` | `boolean` | Pointer and keyboard interaction. Default `true`. |
+| `maxDpr` | `number` | Cap on device pixel ratio. Default `2`. |
+| `onNavigate` | `(href, event) => void` | Use your router instead of a full page load. |
+| `seed` | `number` | Seed for anything random. |
+
+### Theme variables
+
+`--lp-bg --lp-fg --lp-muted --lp-accent --lp-accent-fg --lp-font --lp-font-display --lp-font-mono --lp-font-serif --lp-code-color --lp-code-size --lp-title-size --lp-radius --lp-pad`
+
+Set them from the `theme` option or from your own CSS:
+
+```css
+.lp-root { --lp-font: "Satoshi", sans-serif; --lp-accent: #ff4d2e; --lp-radius: 8px; }
+```
+
+Scenes never load web fonts themselves. If your site already loads Inter, Fraunces or JetBrains Mono, they're used automatically.
+
+### Your own content
+
+```tsx
+<LostPage scene="aurora">
+  <MyBrandedErrorCard />
+</LostPage>
+```
+
+Vue uses the default slot. With the web component, child elements become the content.
+
+## Writing your own scene
+
+```ts
+import { defineScene, mount } from "lostpage/core";
+
+const mine = defineScene({
+  id: "my-404", name: "Mine", description: "…", category: "Abstract",
+  kind: "2d", motion: "live", tags: [], layout: "center",
+  copy: { title: "Not here." }, params: { color: "#ff4d2e" },
+  setup(ctx) {
+    const canvas = ctx.canvas(); // kept sized to the component
+    const g = canvas.getContext("2d")!;
+    return { frame(t) { /* draw */ }, destroy() {} };
+  },
+});
+
+mount(document.body, mine);
+```
+
+## Scenes
+
+<!-- scenes:start -->
+116 scenes, 666 designs. Use the id with `scene="…"` and any preset with `preset="…"`.
+
+### Abstract
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Double Helix | `dna` | 3D · live | `default` `dark` `mono` |
+| Hypnosis | `hypnosis` | 2D · live | `default` `ocean` `toxic` `candy` `rings` `tunnel` |
+| Ink in Water | `ink` | 2D · live | `default` `ocean` `green` `violet` `sumi` `crimson` `teal` `night` |
+| Kaleidoscope | `kaleidoscope` | 2D · live | `default` `ocean` `autumn` `jewel` `pastel` `mono` |
+| Lava Lamp | `lava-lamp` | 2D · live | `default` `neon` `ocean` `lemon` `mint` `sunset` `milk` `blue` |
+| Game of Life | `life` | 2D · live | `default` `matrix` `candy` `paper` `heat` `tiny` |
+| Mesh Gradient | `mesh-gradient` | 2D · live | `default` `ocean` `sunset` `forest` `midnight` `peach` `mono` |
+| Particle Field | `particles` | 2D · interactive | `default` `neon` `gold` `sakura` `smoke` `ocean` `embers` `snow` `confetti` `sand` `pixels` `ink` `fireflies` |
+| Topographic | `topographic` | 2D · live | `default` `night` `tinted` `blue` `ink` |
+
+### Games
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Block Drop | `block-drop` | 2D · live | `default` `pocket` `pastel` `mono` |
+| Brick Breaker | `breakout` | 2D · game | `default` `candy` `ice` `lava` `gameboy` `paper` `neon` `mono` |
+| Claw Machine | `claw-machine` | 2D · game | `default` `blue` `mint` `gold` |
+| Page Invaders | `invaders` | 2D · game | `default` `neon` `green` `mono` `blush` `amber` |
+| Labyrinth | `maze` | 2D · game | `default` `blueprint` `candy` `neon` `hedge` |
+| Table Tennis | `pong` | 2D · game | `default` `synth` `amber` `ice` `tennis` `table` `paper` `neon` |
+| Quest Log | `rpg-dialog` | 2D · live | `default` `desert` `dungeon` `snow` |
+| Offline Runner | `runner` | 2D · game | `default` `ocean` `forest` `mars` `night` `desert` `synth` |
+| Snake | `snake` | 2D · game | `default` `neon` `desert` `mono` `nokia` `candy` `ocean` |
+
+### Nature
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Northern Lights | `aurora` | 2D · live | `default` `rainbow` `faint` `gold` `teal` `violet` `crimson` `ice` `dusk` |
+| Autumn Leaves | `autumn` | 2D · live | `default` `cherry` `dusk` `ginkgo` |
+| Written in Sand | `beach` | 2D · live | `default` `night` `lagoon` `black` `sunset` `pink` `nordic` |
+| Campfire | `campfire` | 2D · live | `default` `autumn` `green` `desert` `blue` `winter` |
+| Murmuration | `flock` | 2D · live | `default` `starlings` `koi` `reef` `drones` `morning` |
+| Foggy Glass | `foggy-glass` | 2D · interactive | `default` `rain` `forest` `sunset` |
+| Mirage | `mirage` | 2D · live | `default` `salt` `dusk` `white` |
+| Koi Pond | `pond` | 2D · live | `default` `sakura` `jade` `night` `autumn` `rain` |
+| Thunderstorm | `thunderstorm` | 2D · live | `default` `purple` `dust` `sea` |
+| Zen Garden | `zen-garden` | 2D · interactive | `default` `moss` `dark` `rose` |
+
+### Ocean
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Sunken Sign | `deep-sea` | 2D · live | `default` `kelp` `red` `tropical` `abyss` |
+| Lighthouse | `lighthouse` | 2D · live | `default` `aurora` `storm` `dusk` |
+| Lost at Sea | `lost-at-sea` | 3D · live | `default` `midday` `red-dawn` `starless` `monsoon` `lavender` `golden-hour` `moonlit` `storm` `fog` `bioluminescent` `arctic` |
+
+### Paper & Print
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Chalkboard | `chalkboard` | 2D · live | `default` `black` `blue` `white` |
+| Cross Stitch | `cross-stitch` | 2D · live | `default` `navy` `rainbow` `dark` |
+| Risograph | `halftone` | 2D · live | `default` `citrus` `sunset` `mono` `news` |
+| Extra! Extra! | `newspaper` | 2D · live | `default` `gazette` `tech` `sports` `tabloid` `pink` `noir` |
+| Receipt | `receipt` | 2D · live | `default` `dark` `cafe` `pink` |
+| Torn Page | `torn-page` | 2D · live | `default` `mint` `newsprint` `cobalt` `kraft` `blueprint` `red` `midnight` |
+| Here Be Dragons | `treasure-map` | 2D · live | `default` `tropic` `blueprint` `night` `nautical` `sepia` |
+| Typewriter | `typewriter` | 2D · live | `default` `noir` `love` `telegram` |
+
+### Physics
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Dominoes | `dominoes` | 2D · live | `default` `wood` `marble` `neon` |
+| Hanging Letters | `hanging-letters` | 2D · live | `default` `autumn` `neon` `paper` `noir` `pastel` |
+| Hanging Sign | `hanging-sign` | 2D · live | `default` `mint` `brick` `closed` `metal` `night` |
+| Unplugged | `unplugged` | 2D · live | `default` `mint` `dark` `orange` |
+
+### Playful
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Foil Balloons | `balloon-404` | 3D · live | `default` `birthday` `pastel` `lime` `violet` `gold` `rainbow` `rose-gold` `blue` |
+| Toy Bricks | `bricks` | 2D · live | `default` `pastel` `space` `mono` |
+| Bubble Wrap | `bubble-wrap` | 2D · interactive | `default` `mint` `pink` `kraft` `night` |
+| Evidence Board | `evidence-board` | 2D · interactive | `default` `blue` `noir` `whiteboard` |
+| Flatline | `flatline` | 2D · live | `default` `amber` `blue` `paper` |
+| Broken Machine | `gears` | 2D · live | `default` `copper` `neon` `brass` `blueprint` |
+| Still Loading | `loading` | 2D · live | `default` `dark` `warm` `dialog` `terminal` |
+| Magic 8 Ball | `magic-8-ball` | 2D · interactive | `default` `gold` `mint` `pink` `crystal` |
+| Missing | `milk-carton` | 3D · interactive | `default` `banana` `matcha` `blueberry` `strawberry` `chocolate` `oat` `night` |
+| Paint Splash | `paint-splash` | 2D · live | `default` `mono` `neon` `pastel` `gold` |
+| Paper Plane | `paper-plane` | 2D · live | `default` `mint` `sunset` `night` `notebook` |
+| Scratch Card | `scratch-card` | 2D · interactive | `default` `classic` `mint` `neon` |
+| Skywriting | `skywriting` | 2D · live | `default` `sunset` `pink` `night` |
+| Jackpot | `slot-machine` | 2D · interactive | `default` `candy` `cyber` `mint` `noir` |
+| Snow Globe | `snow-globe` | 2D · interactive | `default` `rose` `ocean` `mint` `gold` |
+| Empty Stage | `stage` | 2D · live | `default` `green` `purple` `blue` `gold` `comedy` |
+| Sold Out | `vending-machine` | 2D · interactive | `default` `green` `blue` `tokyo` |
+
+### Retro Tech
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| ASCII Donut | `ascii-3d` | 3D · live | `default` `red` `ice` `paper` `amber` `blocks` |
+| Fatal Error | `blue-screen` | 2D · live | `default` `green` `black` `classic` `kernel` `restart` `guru` `bios` |
+| Mixtape | `cassette` | 2D · live | `default` `clear` `synth` `mint` |
+| Circuit Board | `circuit-board` | 2D · live | `default` `blue` `black` `purple` |
+| Error Cascade | `error-cascade` | 2D · interactive | `default` `pink` `space` `aqua` `flat` |
+| Digital Rain | `matrix-rain` | 2D · live | `default` `violet` `gold` `hex` `sakura` `amber` `ice` `binary` `blood` `paper` |
+| No Signal | `no-signal` | 2D · live | `default` `flat` `surf` `static` `test-card` `vcr` `green` `amber` |
+| One Bit | `one-bit` | 3D · live | `default` `pocket` `amber` `paper` `ice` |
+| Radar Sweep | `radar` | 2D · live | `default` `red` `weather` `sonar` `amber` |
+| Screensaver | `screensaver` | 2D · live | `default` `neon` `mono` `crt` `pastel` `fast` |
+| Server Room | `server-room` | 2D · live | `default` `blue` `fire` `white` |
+| Terminal | `terminal` | 2D · interactive | `default` `solarized` `nord` `monokai` `light` `commodore` `green` `amber` `paper` `shell` `dracula` `hacker` |
+| Broken Record | `vinyl` | 2D · live | `default` `black` `color` `jazz` |
+
+### Signs & Displays
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Nixie Tubes | `nixie` | 2D · live | `default` `ice` `magenta` `white` `argon` `vfd` `ruby` `brass` |
+| Departures Board | `split-flap` | 2D · live | `default` `delayed` `gate` `ferry` `train` `arrivals` `white` `green` |
+
+### Simple
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Broken Link | `broken-link` | 2D · live | `default` `dark` `teal` |
+| Brutalist | `brutalist` | 2D · static | `default` `pink` `blue` `green` |
+| Card | `card` | 2D · static | `default` `dark` `search` `broken` |
+| Countdown | `countdown` | 2D · live | `default` `dark` `quick` |
+| Divider | `divider` | 2D · static | `default` `dark` `mono` `large` |
+| Dot Grid | `dot-grid` | 2D · static | `default` `dark` `lines` `blueprint` |
+| Editorial | `editorial` | 2D · static | `default` `night` `rose` |
+| Emoji | `emoji` | 2D · live | `default` `ufo` `ghost` `desert` `melting` |
+| Gradient | `gradient-404` | 2D · static | `default` `night` `sunset` `mint` |
+| Helpful Links | `helpful-links` | 2D · static | `default` `dark` `sand` |
+| Minimal | `minimal` | 2D · static | `default` `dark` `emerald` `big` `warm` |
+| Outline | `outline-404` | 2D · static | `default` `paper` `lime` `blue` |
+| Path Not Found | `path-not-found` | 2D · static | `default` `request` `soft` |
+| Search | `search-404` | 2D · static | `default` `dark` `shop` `docs` |
+| Server Default | `server-default` | 2D · static | `default` `apache` `iis` `dark` |
+| Soft Blobs | `soft-blobs` | 2D · live | `default` `peach` `aqua` `night` |
+| Split Panel | `split-panel` | 2D · static | `default` `forest` `ink` `sky` |
+
+### Space
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Drifting Astronaut | `astronaut` | 2D · live | `default` `pink` `sunrise` `mono` `teal` |
+| Event Horizon | `black-hole` | 3D · live | `default` `emerald` `violet` `faint` `ice` `quasar` `crimson` `eclipse` `edgeon` `synth` |
+| Constellation | `constellation` | 2D · live | `default` `aurora` `chart` `dawn` |
+| Hyperspace Jump | `hyperspace` | 2D · live | `default` `ice` `magenta` `sunburst` `mono` `plasma` `red-alert` `emerald` `gold` |
+| Moon Landing | `moon-landing` | 2D · live | `default` `europa` `mars` `blue` |
+| Lonely Planet | `planet` | 3D · live | `default` `jungle` `candy` `ice-giant` `toxic` `dune` `glacier` `giant` `inferno` `ocean` |
+| Missing Planet | `solar-system` | 2D · live | `default` `paper` `neon` |
+| Abducted | `ufo` | 2D · live | `default` `city` `snow` `desert` `retro` `day` |
+| Wormhole | `wormhole` | 3D · live | `default` `sunset` `gold` `toxic` `mono` `rings` `organic` `data` `ice` |
+
+### Spooky
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Watching | `eyes` | 2D · interactive | `default` `owls` `emoji` `cats` `creatures` `abyss` `daylight` |
+| Flashlight | `flashlight` | 2D · interactive | `default` `attic` `hospital` `cellar` `basement` `crypt` `uv` |
+
+### Typography
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Liquid Chrome | `chrome-404` | 3D · live | `default` `titanium` `emerald` `ruby` `pearl` `medals` `gold` `rose-gold` `black-chrome` `holo` `copper` |
+| Soft Clay | `clay-404` | 3D · live | `default` `ocean` `citrus` `berry` `chocolate` `garden` `mint` `lilac` `terracotta` `midnight` `mono` |
+| Prism Glass | `glass-404` | 3D · live | `default` `forest` `ocean` `lava` `lavender` `neon` `aurora` `sunset` `ice` `mono` `candy` |
+| Signal Corruption | `glitch` | 2D · live | `default` `sunset` `ice` `blood` `blueprint` `vapor` `print` `toxic` `mono` `calm` |
+| Swiss Poster | `swiss-poster` | 2D · static | `default` `red` `black` `blue` |
+| Voxel Blocks | `voxel-404` | 3D · live | `default` `snow` `desert` `candy` `nether` `neon` |
+
+### Urban
+
+| Scene | id | Type | Presets |
+| --- | --- | --- | --- |
+| Floor 404 | `elevator` | 2D · live | `default` `neon` `deco` `sky` |
+| Fireworks | `fireworks` | 2D · live | `default` `gold` `newyear` `lantern` |
+| Metro Map | `metro-map` | 2D · live | `default` `mono` `night` `pastel` |
+| Neon Sign | `neon-sign` | 2D · live | `default` `vegas` `arcade` `pastel` `bar` `motel` `diner` `tokyo` `blue` `broken` |
+| Rainy Window | `rainy-window` | 2D · live | `default` `green` `tokyo` `blue` `amber` `storm` |
+| Road Closed | `road-closed` | 2D · live | `default` `snow` `night` `desert` |
+| City Lights | `skyline` | 2D · live | `default` `green` `snow` `dusk` `cyber` `cold` |
+<!-- scenes:end -->
+
+## License
+
+MIT © Satender Maurya

package/dist/catalog.d.ts

@@ -0,0 +1,2 @@
+export { catalog } from "./generated/catalog";
+export type { CatalogEntry, CatalogPreset } from "./core/types";