{"_id":"@animastor/web-file","name":"@animastor/web-file","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@animastor/web-file","version":"0.1.0","description":"Preact/Web UI module: Animastor Web File — book import/open/create/close/export UI for the web frontend. NOT a platform-independent or domain module — it renders through Preact and consumes host capabilities only via the injected FilePorts contract (sessi","keywords":["animastor","file","preact","web-ui","frontend","ui-component","signals","book-import","ports-and-adapters"],"type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"sideEffects":false,"scripts":{"build":"tsup","typecheck":"tsc --noEmit","test":"vitest run","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"peerDependencies":{"@preact/signals":">=1.0.0","preact":">=10.5.0"},"devDependencies":{"@preact/signals":"^1.3.0","@preact/preset-vite":"^2.9.0","@testing-library/dom":"^10.4.1","@testing-library/preact":"^3.2.4","happy-dom":"^20.14.0","preact":"^10.24.0","tsup":"^8.3.5","typescript":"^5.6.0","vitest":"^4.1.10"},"license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Animastor/animastor.git","directory":"packages/animastor-web-file"},"homepage":"https://github.com/Animastor/animastor/tree/main/packages/animastor-web-file#readme","bugs":{"url":"https://github.com/Animastor/animastor/issues"},"_id":"@animastor/web-file@0.1.0","gitHead":"88cd791e1c441b90a9a514e98e6ab4170fe8ddc8","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-NvPayUVQZMTKgVTy+GDK0jc3kREo0nvPOefqfIwfYhd+iyuJYcA+r7hsiTMvwXtFF9d8WEroT2XUaYGR8HdL4w==","shasum":"4ba400bcd47ea00160a08bc35ca0cc8a71c258b5","tarball":"https://registry.npmjs.org/@animastor/web-file/-/web-file-0.1.0.tgz","fileCount":6,"unpackedSize":47402,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEmFaMRImzWWxEq0a+xV1YfWRfkSIghU77x2HoVaxCpmAiBkxY228iJawZTp8qBxOI3u+Suwcje2uRs5k1v0urAS8w=="}]},"_npmUser":{"name":"animastor","email":"admin@animastor.in"},"directories":{},"maintainers":[{"name":"animastor","email":"admin@animastor.in"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/web-file_0.1.0_1789140088933_0.30062815241529095"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T15:21:28.726Z","0.1.0":"2026-09-11T15:21:29.068Z","modified":"2026-09-11T15:21:29.382Z"},"maintainers":[{"name":"animastor","email":"admin@animastor.in"}],"description":"Preact/Web UI module: Animastor Web File — book import/open/create/close/export UI for the web frontend. NOT a platform-independent or domain module — it renders through Preact and consumes host capabilities only via the injected FilePorts contract (sessi","homepage":"https://github.com/Animastor/animastor/tree/main/packages/animastor-web-file#readme","keywords":["animastor","file","preact","web-ui","frontend","ui-component","signals","book-import","ports-and-adapters"],"repository":{"type":"git","url":"git+https://github.com/Animastor/animastor.git","directory":"packages/animastor-web-file"},"bugs":{"url":"https://github.com/Animastor/animastor/issues"},"license":"MIT","readme":"# @animastor/web-file\n\nBook import/open/create/close/export UI for Animastor, packaged as a standalone Preact module.\n\n> **Scope — Preact/Web UI module.** This package is a **specialized Web/Frontend UI module** built on **Preact** (+ `@preact/signals`), for embedding into browser-based Animastor hosts (`frontends/app`). It is **not** a platform-independent or domain module: it renders DOM through Preact JSX. It is **not intended for Android/native UI** — the Android File surface (`FileFragment` / `fragment_file.xml`) remains a separate native implementation; this package does not target it directly. Domain logic (book session, import flows, generation/player integration) stays host-owned behind the ports — extracting a cross-platform `file-core` is a possible future task, not part of this package.\n\nThe File owns no runtime infrastructure. Every host dependency — session identity, import/open/create/close actions, HTTP downloads, i18n, toast notifications, navigation, desktop open-requests, deep-link handling, icons — arrives through the [`FilePorts`](#fileports) contract injected as a prop. The package never imports host stores, the API client, router, i18n or icon kit, so it can be mounted by any **Preact** host that implements the ports.\n\n## Install\n\n```sh\nnpm install @animastor/web-file\n```\n\nPeer dependencies (must be provided by the host):\n\n- `preact` >= 10.5\n- `@preact/signals` >= 1\n\n## Usage\n\n```tsx\nimport { render } from 'preact';\nimport { FilePage, type FilePorts } from '@animastor/web-file';\n\nconst ports: FilePorts = {\n  session: { bookId, buildId, phase, errorMessage, importMessages, isExporting, navigationEvent },\n  actions: { importBookFromFile, openBookById, closeBook, createBlankBook, setExporting, setExportProgress },\n  http: { getBlob },\n  i18n: { t, tf },\n  toast: { toast },\n  navigation: { navigate },\n  openRequests: { onOpenRequest },\n  deepLink: { takeBookParam },\n  icons: { Folder, Add, Library, Download, Image, VolumeUp, Video },\n};\n\nrender(<FilePage ports={ports} />, document.getElementById('app'));\n```\n\n## Public API\n\n| Export | Kind | Purpose |\n|---|---|---|\n| `FilePage` | component | The File surface; takes `{ path?: string; ports: FilePorts }` |\n| `FilePorts` | type | The full host contract (9 ports, see below) |\n| Individual port types | types | `FileSessionPort`, `FileActionsPort`, `FileHttpPort`, `FileI18nPort`, `FileToastPort`, `FileNavigationPort`, `FileOpenRequestPort`, `FileDeepLinkPort`, `FileIconsPort` |\n| Payload types | types | `FilePhase`, `FileNavigationEvent`, `FileRoute`, `FileExportType`, `FileI18nKey`, `FileIconProps`, `FileIconComponent` |\n\n### FilePorts\n\n| Port | Role |\n|---|---|\n| `session` (`FileSessionPort`) | Shared book identity + File screen state signals |\n| `actions` (`FileActionsPort`) | Import/open/create/close book + export state |\n| `http` (`FileHttpPort`) | Blob download for exports |\n| `i18n` (`FileI18nPort`) | `t`/`tf` for the File's i18n keys |\n| `toast` (`FileToastPort`) | Export-failure toast notifications |\n| `navigation` (`FileNavigationPort`) | Router: `/play` \\| `/generate` \\| `/edit` \\| `/library` |\n| `openRequests` (`FileOpenRequestPort`) | Desktop \"Open\" action subscription |\n| `deepLink` (`FileDeepLinkPort`) | `?book=`/`?open=` URL param consumption |\n| `icons` (`FileIconsPort`) | 7 icon components (Folder, Add, Library, Download, Image, VolumeUp, Video) |\n\n## Behavior contract\n\n- Import: `<input type=file>` + drag-drop → POST /book/import (multipart); navigates to Play/Generate when done.\n- Create New Book: POST /book/blank → navigate to Editor.\n- Library: navigate to `/library`.\n- Download section: book needs bookId; media need bookId + buildId + ready phase.\n- Deep link: `/file?book=<id>` loads an existing server-side book.\n- Desktop open-request: `animastor:open-file` CustomEvent → triggers the file picker.\n- NavigationEvent one-shot: consume-and-reset handshake (Android hasSwitchedToPlay parity).\n\n## Package boundary\n\n- The package imports only `preact`, `preact/hooks`, `preact/jsx-runtime` and `@preact/signals`.\n- Host stores, `api/client`, router, i18n, icons, `AppShell` and adapter modules are **forbidden** inside the package (enforced by boundary tests in the repository).\n- `@animastor/web-file → host` = forbidden; `host → @animastor/web-file` = allowed through the public entry point only.\n- **Technology boundary**: `@animastor/web-file` is a **Preact/Web UI module** — not a cross-platform or domain package. The Android/native File surface is out of scope.\n\n## Development\n\n```sh\nnpm install\nnpm run typecheck   # tsc --noEmit\nnpm run test        # vitest (characterization + boundary tests)\nnpm run build       # tsup → dist/ (ESM + d.ts + sourcemaps)\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-265799d6e479b4361e3fd49bd1630388"}