From 084aa183d9c3aa871de0ac29f7fef353dcd37162 Mon Sep 17 00:00:00 2001 From: Andres Pirela <60560109+andreespirela@users.noreply.github.com> Date: Sat, 3 Oct 2026 22:22:19 -0400 Subject: [PATCH] Add the landing page and shared Markdown docs --- .github/workflows/deploy-site.yml | 45 + .gitignore | 10 +- .idea/.gitignore | 8 - CONTRIBUTING.md | 32 + Cargo.lock | 11 + Cargo.toml | 2 +- README.md | 13 +- apps/.gitignore | 1 + apps/Cargo.lock | 1137 ++++++++++++++++++++++++++ apps/Cargo.toml | 20 + apps/docs/.gitignore | 5 + apps/docs/Cargo.toml | 29 + apps/docs/README.md | 36 + apps/docs/build.rs | 32 + apps/docs/navigation.json | 11 + apps/docs/public/brand.css | 18 + apps/docs/src/app.rs | 73 ++ apps/docs/src/lib.rs | 1 + apps/docs/web/index.html | 36 + apps/landing/.gitignore | 4 + apps/landing/Cargo.toml | 36 + apps/landing/README.md | 36 + apps/landing/build.rs | 118 +++ apps/landing/public/copy.svg | 4 + apps/landing/public/landing.css | 600 ++++++++++++++ apps/landing/src/app.rs | 94 +++ apps/landing/src/examples/boxes.rs | 9 + apps/landing/src/examples/counter.rs | 19 + apps/landing/src/examples/files.rs | 7 + apps/landing/src/examples/menu.rs | 28 + apps/landing/src/examples/mod.rs | 27 + apps/landing/src/examples/search.rs | 21 + apps/landing/src/examples/tables.rs | 24 + apps/landing/src/lib.rs | 3 + apps/landing/src/terminal.rs | 123 +++ apps/landing/ui/boxes.html | 17 + apps/landing/ui/counter.html | 13 + apps/landing/ui/menu.html | 18 + apps/landing/ui/search.html | 17 + apps/landing/ui/tables.html | 20 + apps/landing/ui/terminal.css | 37 + apps/landing/web/index.html | 162 ++++ crates/hypercmd/Cargo.toml | 3 + crates/hypercmd/src/services.rs | 6 +- docs/async.md | 139 ++-- docs/cli.md | 109 +++ docs/consumption.md | 81 +- docs/controls.md | 140 ++-- docs/index.md | 26 + docs/native.md | 177 ++-- docs/profile.md | 339 +++++--- docs/routing.md | 109 ++- docs/services.md | 115 ++- justfile | 51 +- scripts/browser-app.mjs | 57 ++ scripts/browser.mjs | 46 +- scripts/docs.mjs | 67 ++ scripts/landing.mjs | 167 ++++ scripts/site.mjs | 31 + tests/browser-consumer/Cargo.lock | 11 + tests/consumer/Cargo.lock | 79 ++ vercel.json | 34 + 62 files changed, 4288 insertions(+), 456 deletions(-) create mode 100644 .github/workflows/deploy-site.yml delete mode 100644 .idea/.gitignore create mode 100644 apps/.gitignore create mode 100644 apps/Cargo.lock create mode 100644 apps/Cargo.toml create mode 100644 apps/docs/.gitignore create mode 100644 apps/docs/Cargo.toml create mode 100644 apps/docs/README.md create mode 100644 apps/docs/build.rs create mode 100644 apps/docs/navigation.json create mode 100644 apps/docs/public/brand.css create mode 100644 apps/docs/src/app.rs create mode 100644 apps/docs/src/lib.rs create mode 100644 apps/docs/web/index.html create mode 100644 apps/landing/.gitignore create mode 100644 apps/landing/Cargo.toml create mode 100644 apps/landing/README.md create mode 100644 apps/landing/build.rs create mode 100644 apps/landing/public/copy.svg create mode 100644 apps/landing/public/landing.css create mode 100644 apps/landing/src/app.rs create mode 100644 apps/landing/src/examples/boxes.rs create mode 100644 apps/landing/src/examples/counter.rs create mode 100644 apps/landing/src/examples/files.rs create mode 100644 apps/landing/src/examples/menu.rs create mode 100644 apps/landing/src/examples/mod.rs create mode 100644 apps/landing/src/examples/search.rs create mode 100644 apps/landing/src/examples/tables.rs create mode 100644 apps/landing/src/lib.rs create mode 100644 apps/landing/src/terminal.rs create mode 100644 apps/landing/ui/boxes.html create mode 100644 apps/landing/ui/counter.html create mode 100644 apps/landing/ui/menu.html create mode 100644 apps/landing/ui/search.html create mode 100644 apps/landing/ui/tables.html create mode 100644 apps/landing/ui/terminal.css create mode 100644 apps/landing/web/index.html create mode 100644 docs/cli.md create mode 100644 docs/index.md create mode 100644 scripts/browser-app.mjs create mode 100644 scripts/docs.mjs create mode 100644 scripts/landing.mjs create mode 100644 scripts/site.mjs create mode 100644 vercel.json diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml new file mode 100644 index 0000000..8f12d8c --- /dev/null +++ b/.github/workflows/deploy-site.yml @@ -0,0 +1,45 @@ +name: Deploy site +on: + workflow_dispatch: + inputs: + environment: + description: Deploy to production or a preview URL + type: choice + options: [production, preview] + default: production + +permissions: + contents: read + +concurrency: + group: deploy-site + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + timeout-minutes: 45 + environment: vercel + env: + VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }} + VERCEL_ORG_ID: team_hpDr5Biqje4Idy2xKGjdDRsn + VERCEL_PROJECT_ID: prj_mZT9IE4DA026iIKAAinEH5rblXj6 + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + with: + targets: wasm32-unknown-unknown + - uses: Swatinem/rust-cache@v2 + with: + workspaces: apps -> target + - uses: actions/setup-node@v4 + with: + node-version: 22 + - uses: taiki-e/install-action@v2 + with: + tool: just + - run: cargo install fusor-cli --version 0.1.4 --locked + - run: fusor install --manifest-path apps/Cargo.toml -p hypercmd-docs --locked + - run: npm install --global vercel@59.23.2 + - run: vercel pull --yes --environment=${{ inputs.environment }} + - run: just deploy ${{ inputs.environment }} diff --git a/.gitignore b/.gitignore index 6a7359f..b54b58c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,12 @@ /target/ **/target/ node_modules/ -tests/browser-consumer/dist/ +dist/ .idea -.idea/ \ No newline at end of file +.idea/ +.fusor/ +.fusor-stage-*/ +.vercel/ +.env* +.DS_Store +test-results/ diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index 13566b8..0000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Default ignored files -/shelf/ -/workspace.xml -# Editor-based HTTP Client requests -/httpRequests/ -# Datasource local storage ignored files -/dataSources/ -/dataSources.local.xml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index caa4738..806bfd8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,15 @@ On a fresh machine, run `just fetch` before the offline archive gate. Browser component changes also require `just setup-browser` once and `just browser`. See `docs/consumption.md` for the archive output. +The browser apps share a separate Cargo workspace under `apps/`, with the landing +page at `/` and the `docs-base` documentation app at `/docs/`. Run `just site` to +build both into `apps/dist/`, then `just preview` to serve them on port 4187. +`just preview 8080` selects another port. `FUSOR_BIN` can select a local Fusor +CLI. The individual `landing-dev` and `docs-dev` recipes serve one app. +See `apps/docs/README.md` for authoring. +`just check` includes both apps’ native checks; `just browser` includes their +browser suites and the combined-site navigation check. + The runtime and build helper consume fusor's supported public backend contracts. Do not copy fusor's semantic lowering, reactive machinery or route matching. Preserve token streams through `quote!`. An upstream gap needs a minimal @@ -22,6 +31,29 @@ lifecycle/reentrancy, unbounded work, duplicated paths, speculative abstractions misleading comments and tests that mirror implementation. Resolve blocking findings before advancing. +## Deploying the site + +The **Deploy site** workflow builds the landing page and docs with Rust, then +uploads prebuilt files to the Pirela team's `hypercmd` project on Vercel. Run it +from the Actions tab and choose production or preview. Pushes do not deploy. +Vercel's build machines do not provide the Rust toolchain this site needs. + +For a local deployment, install the site prerequisites with +`cargo install fusor-cli --version 0.1.4 --locked` and +`fusor install --manifest-path apps/Cargo.toml -p hypercmd-docs --locked`. +Install Vercel CLI 59.23.2, then run `vercel login` and +`vercel link --yes --scope pirela --project hypercmd` once. Run +`vercel pull --yes --environment=production`, then `just deploy`. +For a preview, pull the preview environment and run `just deploy preview`. + +`vercel.json` serves the docs under `/docs/`, including direct page links. +The deployment recipe removes Fusor build manifests, which contain local paths, +from the upload. Build output, `.vercel/` and local environment files are ignored. + +The workflow reads `VERCEL_TOKEN` from the GitHub environment named `vercel`. +Use a token scoped to this Vercel project when replacing that secret. The team +and project IDs in the workflow are identifiers, not credentials. + ## Releasing Every crate shares one version: `version` under `[workspace.package]` in the diff --git a/Cargo.lock b/Cargo.lock index e01e58b..126c799 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -558,6 +558,7 @@ dependencies = [ "taffy", "unicode-segmentation", "unicode-width 0.2.0", + "web-time", ] [[package]] @@ -1335,6 +1336,16 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + [[package]] name = "winapi" version = "0.3.9" diff --git a/Cargo.toml b/Cargo.toml index 02d1935..3c50b0c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] members = ["crates/hypercmd", "crates/hypercmd-build", "crates/hypercmd-cli", "examples/file-browser", "examples/job-inspector", "examples/job-controls"] -exclude = ["tests/consumer", "tests/browser-consumer"] +exclude = ["tests/consumer", "tests/browser-consumer", "apps"] resolver = "2" [workspace.package] diff --git a/README.md b/README.md index e89f532..21f8a08 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,9 @@ cd my-app hypercmd run ``` -`hypercmd new` writes the counter above and checks that it builds. Edit `ui/app.html` for the screen and `src/main.rs` for its state, then `hypercmd run` again. Run `hypercmd --help` for the other commands. +`hypercmd new` writes the counter above and checks that it builds. Edit +`ui/app.html` for the screen and `src/main.rs` for its state, then `hypercmd run` +again. See the [CLI reference](docs/cli.md) for commands and options. ### Author an application @@ -140,9 +142,16 @@ To run the examples from a checkout, use [`just`](https://github.com/casey/just) ## Documentation +The Markdown guides also power a site through +[`docs-base`](https://github.com/fusor-rs/docs-base). +The [landing page](apps/landing/README.md) and docs share a browser workspace. +Run `just site`, then `just preview` to serve both on port 4187. +See [the site guide](apps/docs/README.md). + | Guide | Covers | | --- | --- | -| [Terminal profile](docs/profile.md) | Supported HTML, CSS, layout, scrolling and Unicode policy | +| [CLI reference](docs/cli.md) | Installation, creating apps, checks, running and building | +| [HTML and CSS reference](docs/profile.md) | Supported HTML, CSS, layout, scrolling and Unicode policy | | [Controls](docs/controls.md) | Keyboard, focus, buttons, text and checkbox bindings | | [Async views](docs/async.md) | `Async`/`Await`, coherent publication and cancellation | | [Routing](docs/routing.md) | Screens, nested views and in-memory history | diff --git a/apps/.gitignore b/apps/.gitignore new file mode 100644 index 0000000..178135c --- /dev/null +++ b/apps/.gitignore @@ -0,0 +1 @@ +/dist/ diff --git a/apps/Cargo.lock b/apps/Cargo.lock new file mode 100644 index 0000000..bc9b822 --- /dev/null +++ b/apps/Cargo.lock @@ -0,0 +1,1137 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "adler2" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "allocator-api2" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923" + +[[package]] +name = "arrayvec" +version = "0.7.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56" + +[[package]] +name = "bincode" +version = "1.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1f45e9417d87227c7a56d22e471c6206462cba514c7590c09aff4cf6d1ddcad" +dependencies = [ + "serde", +] + +[[package]] +name = "bit-set" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3" +dependencies = [ + "bit-vec", +] + +[[package]] +name = "bit-vec" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "cassowary" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df8670b8c7b9dae1793364eafadf7239c40d669904660c5960d74cfd80b46a53" + +[[package]] +name = "castaway" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dec551ab6e7578819132c713a93c022a05d60159dc86e7a7050223577484c55a" +dependencies = [ + "rustversion", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "compact_str" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7fd622ebbb56a5b2ccb651b32b911cdeb2a9b4b11776b2473bf26a26a286244e" +dependencies = [ + "castaway", + "cfg-if", + "itoa", + "rustversion", + "ryu", + "static_assertions", +] + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "crc32fast" +version = "1.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "darling" +version = "0.20.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc7f46116c46ff9ab3eb1597a45688b6715c6e628b5c133e288e709a29bcb4ee" +dependencies = [ + "darling_core", + "darling_macro", +] + +[[package]] +name = "darling_core" +version = "0.20.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d00b9596d185e565c2207a0b01f8bd1a135483d02d9b7b0a54b11da8d53412e" +dependencies = [ + "fnv", + "ident_case", + "proc-macro2", + "quote", + "strsim", + "syn 2.0.119", +] + +[[package]] +name = "darling_macro" +version = "0.20.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead" +dependencies = [ + "darling_core", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "derive-where" +version = "1.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e2b94854e8576378ccda7c8de8a66ed8b4e8acbd2c50ec3418ea6c8aaf4b567" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", +] + +[[package]] +name = "docs-base" +version = "0.1.0" +source = "git+https://github.com/fusor-rs/docs-base?rev=e2c7b3939721002ea2aa7556d8e4409aa131472b#e2c7b3939721002ea2aa7556d8e4409aa131472b" +dependencies = [ + "fusor-build", + "fusor-components", + "fusor-core", + "wasm-bindgen", + "web-sys", +] + +[[package]] +name = "docs-base-build" +version = "0.1.0" +source = "git+https://github.com/fusor-rs/docs-base?rev=e2c7b3939721002ea2aa7556d8e4409aa131472b#e2c7b3939721002ea2aa7556d8e4409aa131472b" +dependencies = [ + "proc-macro2", + "pulldown-cmark", + "quote", + "serde", + "serde_json", + "syntect", + "two-face", +] + +[[package]] +name = "either" +version = "1.18.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34" + +[[package]] +name = "equivalent" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f" + +[[package]] +name = "fancy-regex" +version = "0.16.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "998b056554fbe42e03ae0e152895cd1a7e1002aec800fdc6635d20270260c46f" +dependencies = [ + "bit-set", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "flate2" +version = "1.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb" +dependencies = [ + "crc32fast", + "miniz_oxide", + "zlib-rs", +] + +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + +[[package]] +name = "foldhash" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "fusor-async" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "804497a690960b93fe23366f41f968d923e60e9025eee19180e9d63f2a7d70d2" +dependencies = [ + "derive-where", + "fusor-core", + "futures-util", +] + +[[package]] +name = "fusor-build" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61e853f1efe0a7a43a69c1b0ba429a65e3fb2b059a9839522bea725452a325d5" +dependencies = [ + "fusor-core", + "fusor-islands", + "fusor-router", + "html5gum", + "proc-macro2", + "quote", + "serde", + "serde_json", + "sha2", + "syn 2.0.119", + "toml", +] + +[[package]] +name = "fusor-components" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ff376904a2eadb6a540744719429734482d2e736a0773377d9853fe170613f5" +dependencies = [ + "fusor-core", +] + +[[package]] +name = "fusor-core" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "36cc8392e17b5eea5f45606a51bb8736042bd19175f20fb63ee82fc1787561eb" +dependencies = [ + "fusor-macros", + "js-sys", + "wasm-bindgen", + "web-sys", +] + +[[package]] +name = "fusor-islands" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09040f3dfaa95e41e54a4ba1005a88e017910b0eceee4e700c5f04be3c47ce22" +dependencies = [ + "fusor-core", + "serde", + "serde_json", +] + +[[package]] +name = "fusor-macros" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebdbd0919aeab94a1589b0952a9711e7d46aab3123a0c2c02ba3b0683d814490" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "fusor-router" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1cbb73da8ceba9583442a661d65d9d1256ee2863a55ee1ec95f8e5d4b4507070" +dependencies = [ + "form_urlencoded", + "fusor-core", + "js-sys", + "percent-encoding", + "wasm-bindgen", + "web-sys", +] + +[[package]] +name = "futures-channel" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4" +dependencies = [ + "futures-core", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-core", + "futures-task", + "pin-project-lite", + "slab", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "grid" +version = "0.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "36119f3a540b086b4e436bb2b588cf98a68863470e0e880f4d0842f112a3183a" + +[[package]] +name = "hashbrown" +version = "0.15.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1" +dependencies = [ + "allocator-api2", + "equivalent", + "foldhash", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "html5gum" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "428502d3ec1742c35e015871aef742bc4722a9acfcb616b8ff79b519922e1c36" + +[[package]] +name = "hypercmd" +version = "0.1.0" +dependencies = [ + "fusor-async", + "fusor-core", + "fusor-router", + "futures-channel", + "futures-util", + "instability", + "ratatui", + "taffy", + "unicode-segmentation", + "unicode-width 0.2.0", + "web-time", +] + +[[package]] +name = "hypercmd-build" +version = "0.1.0" +dependencies = [ + "fusor-build", + "proc-macro2", + "quote", + "serde", + "syn 2.0.119", + "toml", +] + +[[package]] +name = "hypercmd-docs" +version = "0.1.0" +dependencies = [ + "docs-base", + "docs-base-build", + "fusor-build", + "fusor-components", + "fusor-core", + "fusor-router", + "wasm-bindgen", +] + +[[package]] +name = "hypercmd-landing" +version = "0.1.0" +dependencies = [ + "docs-base-build", + "fusor-build", + "fusor-components", + "fusor-core", + "hypercmd", + "hypercmd-build", + "quote", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", +] + +[[package]] +name = "ident_case" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39" + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown 0.17.1", +] + +[[package]] +name = "indoc" +version = "2.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706" +dependencies = [ + "rustversion", +] + +[[package]] +name = "instability" +version = "0.3.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6778b0196eefee7df739db78758e5cf9b37412268bfa5650bfeed028aed20d9c" +dependencies = [ + "darling", + "indoc", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "itertools" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186" +dependencies = [ + "either", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "js-sys" +version = "0.3.94" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e04e2ef80ce82e13552136fabeef8a5ed1f985a96805761cbb9a2c34e7664d9" +dependencies = [ + "cfg-if", + "futures-util", + "once_cell", + "wasm-bindgen", +] + +[[package]] +name = "libc" +version = "0.2.190" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78" + +[[package]] +name = "lru" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "234cf4f4a04dc1f57e24b96cc0cd600cf2af460d4161ac5ecdd0af8e1f3b2a38" +dependencies = [ + "hashbrown 0.15.5", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "miniz_oxide" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "paste" +version = "1.0.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "pulldown-cmark" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e8bbe1a966bd2f362681a44f6edce3c2310ac21e4d5067a6e7ec396297a6ea0" +dependencies = [ + "bitflags", + "memchr", + "pulldown-cmark-escape", + "unicase", +] + +[[package]] +name = "pulldown-cmark-escape" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae" + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "ratatui" +version = "0.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eabd94c2f37801c20583fc49dd5cd6b0ba68c716787c2dd6ed18571e1e63117b" +dependencies = [ + "bitflags", + "cassowary", + "compact_str", + "indoc", + "instability", + "itertools", + "lru", + "paste", + "strum", + "unicode-segmentation", + "unicode-truncate", + "unicode-width 0.2.0", +] + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + +[[package]] +name = "serde_json" +version = "1.0.151" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_spanned" +version = "0.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3" +dependencies = [ + "serde", +] + +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures", + "digest", +] + +[[package]] +name = "simd-adler32" +version = "0.3.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "slotmap" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bdd58c3c93c3d278ca835519292445cb4b0d4dc59ccfdf7ceadaab3f8aeb4038" +dependencies = [ + "version_check", +] + +[[package]] +name = "static_assertions" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f" + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "strum" +version = "0.26.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06" +dependencies = [ + "strum_macros", +] + +[[package]] +name = "strum_macros" +version = "0.26.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "rustversion", + "syn 2.0.119", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syntect" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "656b45c05d95a5704399aeef6bd0ddec7b2b3531b7c9e900abbf7c4d2190c925" +dependencies = [ + "bincode", + "fancy-regex", + "flate2", + "fnv", + "once_cell", + "regex-syntax", + "serde", + "serde_derive", + "thiserror", + "walkdir", +] + +[[package]] +name = "taffy" +version = "0.7.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab4f4d046dd956a47a7e1a2947083d7ac3e6aa3cfaaead36173ceaa5ab11878c" +dependencies = [ + "arrayvec", + "grid", + "serde", + "slotmap", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + +[[package]] +name = "toml" +version = "0.8.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362" +dependencies = [ + "serde", + "serde_spanned", + "toml_datetime", + "toml_edit", +] + +[[package]] +name = "toml_datetime" +version = "0.6.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c" +dependencies = [ + "serde", +] + +[[package]] +name = "toml_edit" +version = "0.22.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a" +dependencies = [ + "indexmap", + "serde", + "serde_spanned", + "toml_datetime", + "toml_write", + "winnow", +] + +[[package]] +name = "toml_write" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801" + +[[package]] +name = "two-face" +version = "0.5.2+bat-0.26.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "915be7adc2ff6f4338acbf71f3eda0a146f46003b992a1669c674308610efdac" +dependencies = [ + "serde", + "serde_derive", + "syntect", +] + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicase" +version = "2.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142" + +[[package]] +name = "unicode-ident" +version = "1.0.26" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954" + +[[package]] +name = "unicode-segmentation" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493" + +[[package]] +name = "unicode-truncate" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b3644627a5af5fa321c95b9b235a72fd24cd29c648c2c379431e6628655627bf" +dependencies = [ + "itertools", + "unicode-segmentation", + "unicode-width 0.1.14", +] + +[[package]] +name = "unicode-width" +version = "0.1.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af" + +[[package]] +name = "unicode-width" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fc81956842c57dac11422a97c3b8195a1ff727f06e85c84ed2e8aa277c9a0fd" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.117" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0551fc1bb415591e3372d0bc4780db7e587d84e2a7e79da121051c5c4b89d0b0" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-futures" +version = "0.4.67" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03623de6905b7206edd0a75f69f747f134b7f0a2323392d664448bf2d3c5d87e" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.117" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7fbdf9a35adf44786aecd5ff89b4563a90325f9da0923236f6104e603c7e86be" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.117" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dca9693ef2bab6d4e6707234500350d8dad079eb508dca05530c85dc3a529ff2" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 2.0.119", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.117" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39129a682a6d2d841b6c429d0c51e5cb0ed1a03829d8b3d1e69a011e62cb3d3b" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "web-sys" +version = "0.3.94" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd70027e39b12f0849461e08ffc50b9cd7688d942c1c8e3c7b22273236b4dd0a" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "winnow" +version = "0.7.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945" +dependencies = [ + "memchr", +] + +[[package]] +name = "zlib-rs" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/apps/Cargo.toml b/apps/Cargo.toml new file mode 100644 index 0000000..f19de40 --- /dev/null +++ b/apps/Cargo.toml @@ -0,0 +1,20 @@ +[workspace] +members = ["landing", "docs"] +resolver = "2" + +[workspace.metadata.fusor.site] +output = "dist" + +[workspace.metadata.fusor.site.mounts] +"/" = "hypercmd-landing" +"/docs/" = "hypercmd-docs" + +[profile.dev] +debug = 0 + +[profile.release] +opt-level = 3 +lto = true +codegen-units = 1 +panic = "abort" +strip = "debuginfo" diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore new file mode 100644 index 0000000..8150652 --- /dev/null +++ b/apps/docs/.gitignore @@ -0,0 +1,5 @@ +/target/ +/dist/ +/public/content/ +/public/docs-base.css +/public/favicon.svg diff --git a/apps/docs/Cargo.toml b/apps/docs/Cargo.toml new file mode 100644 index 0000000..0b81966 --- /dev/null +++ b/apps/docs/Cargo.toml @@ -0,0 +1,29 @@ +[package] +name = "hypercmd-docs" +version = "0.1.0" +edition = "2024" +rust-version = "1.85" +publish = false + +[lib] +crate-type = ["cdylib", "rlib"] + +[dependencies] +docs-base = { git = "https://github.com/fusor-rs/docs-base", rev = "e2c7b3939721002ea2aa7556d8e4409aa131472b" } +fusor = { package = "fusor-core", version = "=0.1.4", features = ["dom", "derive"] } +fusor-components = { version = "=0.1.4", features = ["browser"] } +fusor-router = { version = "=0.1.4", features = ["browser"] } +wasm-bindgen = "=0.2.117" + +[build-dependencies] +docs-base-build = { git = "https://github.com/fusor-rs/docs-base", rev = "e2c7b3939721002ea2aa7556d8e4409aa131472b" } +fusor-build = "=0.1.4" + +[package.metadata.fusor] +entry = "web/index.html" +assets = "public" +base-path = "/docs/" +history-fallback = ["/"] + +[lints.rust] +unsafe_code = "forbid" diff --git a/apps/docs/README.md b/apps/docs/README.md new file mode 100644 index 0000000..6eb30b2 --- /dev/null +++ b/apps/docs/README.md @@ -0,0 +1,36 @@ +# Hypercmd documentation site + +This browser application consumes the shared +[`docs-base`](https://github.com/fusor-rs/docs-base) compiler and Fusor components. +Guides remain in `../../docs/`, readable on GitHub. `navigation.json` sets groups +and reading order; `public/brand.css` supplies Hypercmd colors. The web apps share +the `apps/` Cargo workspace, separate from the native terminal crates. + +From the Hypercmd repository root, run `just setup-browser` once, then `just site` +to build the combined site into `apps/dist/`. `just preview` serves the landing +page and docs on port 4187; open `/docs/` for the guides. +`just docs-dev` serves the docs alone, and `just docs` builds +`apps/docs/dist/`, including original Markdown at `/docs/content/`. Configure a static +host to serve `apps/docs/dist/index.html` for `/docs/*` routes that are not files. +The site requires JavaScript/Wasm and does not prerender per-page HTML. +The **Deploy site** workflow hosts the combined site on Vercel; see +[deployment setup](../../CONTRIBUTING.md#deploying-the-site). +Markdown lives outside the app directory watched by Fusor; rebuild with +`just site` or restart `just docs-dev` after editing files in `docs/`. + +`just docs-check` checks formatting, Clippy and Rust 1.85. `just docs-browser` +builds and tests every guide in Chromium, including source downloads, links, +history, mobile layout and theme persistence. They are included in the existing +`check` and `browser` gates. `FUSOR_BIN` can select a local Fusor CLI. + +To add a guide, write a Markdown file in `docs/` starting with `# Title` and add +its slug to `apps/docs/navigation.json`. Start with one short introduction, then +use `##` sections for the body. Text before the first `##` uses the larger lead +typography. `##` headings also form the table of contents; +explicit IDs (`## Heading {#stable-id}`) preserve published anchors. Relative +links to registered Markdown files become site routes. Other relative file +links point to Hypercmd repository source. + +Header links and branding belong here. The article shell, navigation, search +and Markdown renderer belong in `docs-base`; update the pinned revision of both +shared crates together when consuming an upstream change. diff --git a/apps/docs/build.rs b/apps/docs/build.rs new file mode 100644 index 0000000..08d1ea5 --- /dev/null +++ b/apps/docs/build.rs @@ -0,0 +1,32 @@ +use docs_base_build::{Config, Highlighter}; +use std::{ + env, fs, + path::{Path, PathBuf}, +}; + +fn main() -> Result<(), Box> { + let directory = PathBuf::from(env::var("CARGO_MANIFEST_DIR")?); + let root = directory + .parent() + .and_then(Path::parent) + .ok_or("the docs app must live in apps/docs inside the Hypercmd repository")?; + let guides = docs_base_build::compile( + &Config { + root, + content: Path::new("docs"), + navigation: Path::new("apps/docs/navigation.json"), + references: None, + base_path: "/docs/", + repository: Some("https://github.com/fusor-rs/hypercmd/blob/main/"), + }, + &Highlighter::default(), + )?; + guides.write_assets(Path::new("public"))?; + fs::write( + PathBuf::from(env::var("OUT_DIR")?).join("guides.rs"), + guides.source.to_string(), + )?; + println!("cargo:rerun-if-changed=../../assets/brand/hypercmd.svg"); + fs::copy(root.join("assets/brand/hypercmd.svg"), "public/favicon.svg")?; + fusor_build::compile_app() +} diff --git a/apps/docs/navigation.json b/apps/docs/navigation.json new file mode 100644 index 0000000..411fc0b --- /dev/null +++ b/apps/docs/navigation.json @@ -0,0 +1,11 @@ +[ + { "slug": "", "group": "Learn" }, + { "slug": "cli", "group": "Reference", "reference": true }, + { "slug": "profile", "group": "Reference", "reference": true }, + { "slug": "controls", "group": "Reference", "reference": true }, + { "slug": "async", "group": "Learn" }, + { "slug": "routing", "group": "Learn" }, + { "slug": "services", "group": "Learn" }, + { "slug": "native", "group": "Reference", "reference": true }, + { "slug": "consumption", "group": "Learn" } +] diff --git a/apps/docs/public/brand.css b/apps/docs/public/brand.css new file mode 100644 index 0000000..8c00779 --- /dev/null +++ b/apps/docs/public/brand.css @@ -0,0 +1,18 @@ +.site { + --bg: #faf9f6; + --panel: #f4f1ed; + --text: #272a2c; + --accent: #a83228; + --wash: #f8eae5; +} +.site.dark { + --bg: #211c1b; + --panel: #292220; + --text: #faf9f6; + --accent: #ff9983; + --wash: #442924; +} + +.markdown td:first-child code { + white-space: nowrap; +} diff --git a/apps/docs/src/app.rs b/apps/docs/src/app.rs new file mode 100644 index 0000000..85f7d55 --- /dev/null +++ b/apps/docs/src/app.rs @@ -0,0 +1,73 @@ +use docs_base::{Location, Navigation, Site}; +use fusor::{ + OwnerHandle, + dom::{Content, FromInputs, JsValue}, +}; +use fusor_router::browser::declarative::Navigation as RouterNavigation; + +include!(concat!(env!("OUT_DIR"), "/guides.rs")); + +static SITE: Site = Site { + name: "hypercmd", + base_path: "/docs/", + logo: "/docs/favicon.svg", + version: "v0.1 dev", + pages: PAGES, +}; + +struct App { + navigation: Navigation, + header: Content, +} + +impl App { + fn new() -> Self { + Self { + navigation: Navigation::new(&SITE), + header: Content::new(|_| Header), + } + } +} + +struct Header; + +struct DocRoute { + index: Option, +} + +struct DocRouteInputs { + navigation: Navigation, +} + +impl FromInputs for DocRoute { + type Inputs = DocRouteInputs; + type Error = JsValue; + + fn from_inputs(inputs: Self::Inputs, owner: OwnerHandle) -> Result { + let router = RouterNavigation::from_owner(&owner) + .ok_or_else(|| JsValue::from_str("missing documentation navigation"))?; + let index = match router.location().get().segments() { + Ok(segments) => { + let slug = segments.join("/"); + PAGES.iter().position(|page| page.slug == slug) + } + // Malformed route encodings use the same missing-page view as unknown paths. + Err(_) => None, + }; + inputs + .navigation + .active + .set(index.map_or(Location::Missing, Location::Guide)); + Ok(Self { index }) + } +} + +#[expect( + clippy::excessive_nesting, + reason = "generated DOM scaffolding: https://github.com/fusor-rs/fusor/issues/17" +)] +mod dom { + use super::{App, DocRoute, Header, SITE}; + use docs_base::{Article, ArticleExtras, Shell}; + fusor::template!("web/index.html"); +} diff --git a/apps/docs/src/lib.rs b/apps/docs/src/lib.rs new file mode 100644 index 0000000..c0de390 --- /dev/null +++ b/apps/docs/src/lib.rs @@ -0,0 +1 @@ +mod app; diff --git a/apps/docs/web/index.html b/apps/docs/web/index.html new file mode 100644 index 0000000..988db2e --- /dev/null +++ b/apps/docs/web/index.html @@ -0,0 +1,36 @@ + + + + + + + hypercmd documentation + + + + + + +
+ + + + + +
+
+ + + + + diff --git a/apps/landing/.gitignore b/apps/landing/.gitignore new file mode 100644 index 0000000..22fd244 --- /dev/null +++ b/apps/landing/.gitignore @@ -0,0 +1,4 @@ +/target/ +/dist/ +/public/brand/ +/public/*.html diff --git a/apps/landing/Cargo.toml b/apps/landing/Cargo.toml new file mode 100644 index 0000000..bb433aa --- /dev/null +++ b/apps/landing/Cargo.toml @@ -0,0 +1,36 @@ +[package] +name = "hypercmd-landing" +version = "0.1.0" +edition = "2024" +rust-version = "1.85" +publish = false + +[lib] +crate-type = ["cdylib", "rlib"] + +[dependencies] +fusor = { package = "fusor-core", version = "=0.1.4", features = ["dom", "derive"] } +fusor-components = { version = "=0.1.4", features = ["browser"] } +hypercmd = { path = "../../crates/hypercmd", default-features = false } +wasm-bindgen = "=0.2.117" +wasm-bindgen-futures = "=0.4.67" +web-sys = { version = "=0.3.94", features = ["Window", "Navigator", "Clipboard", "HtmlInputElement"] } + +[build-dependencies] +docs-base-build = { git = "https://github.com/fusor-rs/docs-base", rev = "e2c7b3939721002ea2aa7556d8e4409aa131472b" } +fusor-build = "=0.1.4" +hypercmd-build = { path = "../../crates/hypercmd-build" } +quote = "=1.0.47" + +[package.metadata.fusor] +entry = "web/index.html" +templates = [] +assets = "public" +base-path = "/" + +[package.metadata.hypercmd] +templates = ["ui"] +styles = ["ui/terminal.css"] + +[lints.rust] +unsafe_code = "forbid" diff --git a/apps/landing/README.md b/apps/landing/README.md new file mode 100644 index 0000000..4bb6420 --- /dev/null +++ b/apps/landing/README.md @@ -0,0 +1,36 @@ +# Hypercmd landing page + +A Fusor browser app at `/`, in the shared `apps/` Cargo workspace. From the +repository root, run `just site` to build the landing page and docs into +`apps/dist/`, then `just preview` to serve them together on port 4187. +`just landing-dev` serves this app alone; `just landing` builds `apps/landing/dist/`. +`FUSOR_BIN` can select a local Fusor CLI. `just setup-browser` installs the tools. + +The five templates in `ui/` are both the editor's displayed source and the input +compiled by Hypercmd. Counter is selected initially; the example buttons switch +between counter, filesystem search, tables, boxes and menu demonstrations. +Switching examples starts a fresh component. The preview paints its terminal cells +and exposes the generated button and text-input handlers as accessible +browser controls, without native terminal dependencies. + +The full HTML and interactive terminal appear together. The example card enters +in 240ms; switching examples fades in both panes over 180ms. Reduced motion +disables these animations. + +Search filters a build-time snapshot of this app's `src/` and `ui/` directories; +the preview shows the first five matches. The table displays the actual sizes of +the HTML files and sorts them on demand. Neither example accesses a visitor's +filesystem. Edit each example's Rust state in `src/examples/` and its terminal +styles in `ui/terminal.css`. The example catalog and terminal viewport heights +live in `build.rs`. + +Brand assets come from `assets/brand/`. The build copies those assets and each +example's downloadable source into `public/`; edit the originals. The page links +to the sibling documentation app at `/docs/` and its CLI reference at `/docs/cli`. +The quick start shows how to create and run an app after installing the CLI. +The combined site mounts both applications; see the root +[deployment guide](../../CONTRIBUTING.md#deploying-the-site) for Vercel hosting. + +`just landing-check` checks formatting, Clippy and Rust 1.85. `just landing-browser` +builds the app and exercises entrance and switching animations, all five terminal +interactions, installation clipboard, and responsive layout in Chromium. diff --git a/apps/landing/build.rs b/apps/landing/build.rs new file mode 100644 index 0000000..12ec1da --- /dev/null +++ b/apps/landing/build.rs @@ -0,0 +1,118 @@ +use docs_base_build::Highlighter; +use quote::{format_ident, quote}; +use std::{env, fs, path::PathBuf}; + +const EXAMPLES: [(&str, &str, &str, u16); 5] = [ + ("Counter", "Counter", "Try +1, then reset.", 13_u16), + ( + "Search", + "Filesystem", + "Search this app's source files. Try .rs or .html.", + 17, + ), + ( + "Tables", + "Tables", + "Real file sizes. Try sorting the rows.", + 18, + ), + ("Boxes", "Boxes", "Switch between columns and rows.", 23), + ( + "Menu", + "Menu", + "Choose a command with a click or Tab + Enter.", + 21, + ), +]; + +fn main() -> Result<(), Box> { + fs::create_dir_all("public/brand")?; + for name in [ + "hypercmd.svg", + "hypercmd-horizontal.svg", + "hypercmd-social.png", + ] { + let source = format!("../../assets/brand/{name}"); + let destination = format!("public/brand/{name}"); + println!("cargo:rerun-if-changed={source}"); + write_asset(&destination, &fs::read(source)?)?; + } + highlighted_examples()?; + project_files()?; + hypercmd_build::compile_app()?; + fusor_build::compile_app() +} + +fn highlighted_examples() -> Result<(), Box> { + let highlighter = Highlighter::default(); + let mut examples = Vec::new(); + for (name, label, hint, rows) in EXAMPLES { + let kind = format_ident!("{name}"); + let filename = format!("{}.html", name.to_lowercase()); + let source = fs::read_to_string(format!("ui/{filename}"))?; + let mut lines = Vec::new(); + for (index, line) in source.lines().enumerate() { + let number = index + 1; + let tokens = highlighter.tokens(line, "html")?; + lines.push(quote! { CodeLine { number: #number, tokens: #tokens } }); + } + examples.push(quote! { + Example { + kind: ExampleKind::#kind, filename: #filename, label: #label, + hint: #hint, rows: #rows, lines: &[#(#lines),*], + } + }); + write_asset(&format!("public/{filename}"), source.as_bytes())?; + } + fs::write( + PathBuf::from(env::var("OUT_DIR")?).join("source.rs"), + quote! { const EXAMPLES: &[Example] = &[#(#examples),*]; }.to_string(), + )?; + Ok(()) +} + +fn project_files() -> Result<(), Box> { + let mut paths = Vec::new(); + for directory in ["src", "ui"] { + collect_files(directory, &mut paths)?; + } + paths.sort(); + let mut files = Vec::new(); + for path in paths { + println!("cargo:rerun-if-changed={path}"); + let bytes = fs::metadata(&path)?.len(); + files.push(quote! { ProjectFile { path: #path, bytes: #bytes } }); + } + fs::write( + PathBuf::from(env::var("OUT_DIR")?).join("files.rs"), + quote! { pub(super) const FILES: &[ProjectFile] = &[#(#files),*]; }.to_string(), + )?; + Ok(()) +} + +fn collect_files(directory: &str, paths: &mut Vec) -> std::io::Result<()> { + println!("cargo:rerun-if-changed={directory}"); + for entry in fs::read_dir(directory)? { + let entry = entry?; + let path = entry.path().to_string_lossy().into_owned(); + if entry.file_type()?.is_dir() { + collect_files(&path, paths)?; + } else if entry.file_type()?.is_file() { + paths.push(path); + } + } + Ok(()) +} + +fn write_asset(path: &str, contents: &[u8]) -> std::io::Result<()> { + println!("cargo:rerun-if-changed={path}"); + let changed = match fs::read(path) { + Ok(current) => current != contents, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => true, + Err(error) => return Err(error), + }; + if changed { + fs::write(path, contents)?; + } + Ok(()) +} diff --git a/apps/landing/public/copy.svg b/apps/landing/public/copy.svg new file mode 100644 index 0000000..d7c08b8 --- /dev/null +++ b/apps/landing/public/copy.svg @@ -0,0 +1,4 @@ + + + + diff --git a/apps/landing/public/landing.css b/apps/landing/public/landing.css new file mode 100644 index 0000000..5ff2a48 --- /dev/null +++ b/apps/landing/public/landing.css @@ -0,0 +1,600 @@ +:root { + color-scheme: light; + --paper: #faf9f6; + --ink: #272a2c; + --oxide: #a83228; + --vermilion: #df5036; + --muted: #76736f; + --line: #e5e1da; + --mono: "SFMono-Regular", Consolas, "Liberation Mono", monospace; + background: var(--paper); + color: var(--ink); + font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; + font-synthesis: none; + -webkit-font-smoothing: antialiased; +} +* { + box-sizing: border-box; +} +body, h1, h2, p, pre { + margin: 0; +} +button, a { + -webkit-tap-highlight-color: transparent; +} +button { + font: inherit; + cursor: pointer; +} +a { + color: inherit; + text-decoration: none; +} +a:hover { + color: var(--oxide); +} +button:focus-visible, input:focus-visible, a:focus-visible, pre:focus-visible { + outline: 2px solid var(--vermilion); + outline-offset: 5px; +} +::selection { + background: #efd0c5; + color: var(--ink); +} +.page { + width: min(1120px, calc(100% - 80px)); + margin-inline: auto; +} +.skip-link { + position: absolute; + top: -60px; + left: 20px; + padding: 12px; + background: var(--paper); + z-index: 2; +} +.skip-link:focus { + top: 12px; +} +.site-header { + height: 102px; + display: flex; + align-items: center; + justify-content: space-between; + border-bottom: 1px solid var(--line); +} +.brand img { + display: block; + height: auto; +} +.family { + font-size: 12px; + color: var(--muted); +} +.family span { + margin-left: 6px; +} +.hero { + text-align: center; + padding: 65px 0 48px; +} +.eyebrow { + display: flex; + justify-content: center; + align-items: center; + gap: 10px; + color: var(--oxide); + font-family: var(--mono); + font-size: 11px; + margin-bottom: 22px; +} +.brand-prompt { + font-size: 16px; + font-weight: 700; + color: var(--vermilion); +} +h1 { + font-size: clamp(40px, 5.6vw, 76px); + font-weight: 630; + line-height: 1.09; + letter-spacing: -0.055em; +} +h1 span { + color: var(--oxide); +} +.description { + margin-top: 25px; + color: #77736e; + font-size: 15px; + line-height: 1.7; +} +.example { + animation: show-example 240ms ease-out both; +} +.example-picker { + display: flex; + justify-content: center; + flex-wrap: wrap; + gap: 6px; + margin-bottom: 20px; +} +.example-button { + padding: 9px 16px; + border: 1px solid transparent; + border-radius: 6px; + background: transparent; + color: var(--muted); + font: 12px var(--mono); +} +.example-button:hover { + color: var(--oxide); + background: #f2f0eb; +} +.example-button[aria-pressed="true"] { + color: var(--oxide); + background: #f2e8e1; + border-color: #e9d3c7; +} +.studio { + display: grid; + grid-template-columns: minmax(0, 1.12fr) minmax(0, 1fr); + overflow: hidden; + border: 1px solid #393a38; + border-radius: 10px; + background: #202221; + color: #d8d8d0; + box-shadow: 0 20px 55px -28px #30261970, 0 2px 6px #28241e0a; + font-family: var(--mono); + font-size: 12px; +} +.editor, .preview { + display: flex; + flex-direction: column; + min-width: 0; +} +.editor { + background: #202221; +} +.preview { + background: #181b1a; + border-left: 1px solid #393a38; +} +.pane-heading { + height: 49px; + padding: 0 21px; + display: flex; + align-items: center; + gap: 12px; + border-bottom: 1px solid #ffffff0c; + color: #c3c5be; +} +.window-controls { + display: flex; + gap: 6px; + margin-right: 14px; +} +.window-controls i { + width: 8px; + height: 8px; + border-radius: 50%; + background: #615551; +} +.window-controls i:nth-child(2) { + background: #686149; +} +.window-controls i:nth-child(3) { + background: #495d50; +} +.filename { + display: flex; + align-items: center; + gap: 8px; +} +.html-icon { + color: #e09b77; + font-size: 14px; +} +.pane-label { + margin-left: auto; + font-size: 10px; + color: #81867f; +} +.terminal-icon { + color: #bdc4b8; + font-size: 15px; +} +.source { + padding: 27px 23px 27px 0; + flex: 1; + min-height: 454px; + overflow-x: auto; + font: 12px/20px var(--mono); + white-space: normal; +} +.source-row { + display: flex; + height: 20px; +} +.line-number { + width: 51px; + flex-shrink: 0; + padding-right: 19px; + text-align: right; + color: #737b73; + user-select: none; +} +.code-line { + display: block; + height: 20px; + white-space: pre; + flex-shrink: 0; +} +.code-line > span { + color: var(--syntax-dark); +} +.pane-footer { + height: 34px; + padding: 0 20px; + display: flex; + align-items: center; + justify-content: space-between; + border-top: 1px solid #ffffff0b; + color: #8c9289; + font-size: 10px; +} +.branch { + color: #b5bbae; + font-size: 14px; + padding-right: 6px; +} +.footer-dot { + padding: 0 7px; +} +.terminal-body { + display: flex; + flex-direction: column; + flex: 1; + padding: 27px 27px 21px; +} +.run-command { + font-size: 11px; + white-space: nowrap; + margin-bottom: 21px; +} +.run-command > span:first-child { + color: #999f93; +} +.shell-prompt { + color: var(--vermilion); + margin: 0 8px; +} +.terminal-screen { + --cell-height: 1em; + margin: auto; + position: relative; + width: calc(var(--terminal-columns) * 1ch); + font-size: 14px; +} +.source, .terminal-screen { + animation: change-example 180ms ease-out both; +} +.terminal-output { + font: inherit; + line-height: var(--cell-height); + color: #c7cec0; +} +.terminal-control { + position: absolute; + padding: 0; + border: 0; + background: transparent; + font: inherit; + border-radius: 2px; +} +.terminal-input { + background: #252b26; + color: #c7cec0; + line-height: var(--cell-height); + caret-color: #e09b77; + border-radius: 0; +} +button.terminal-control:hover { + background: #df503622; +} +.terminal-control:focus-visible { + outline-offset: -2px; +} +.runtime-status { + display: flex; + align-items: center; + gap: 7px; +} +.runtime-status i { + width: 5px; + height: 5px; + background: #93ad8a; + border-radius: 50%; +} +.example-caption { + margin-top: 17px; + color: var(--muted); + font-size: 11px; +} +.example-caption p > span:first-child { + margin-right: 5px; + color: var(--oxide); +} +.try-it { + color: #555850; +} +.installation { + padding: 49px 0 43px; + text-align: center; +} +h2 { + font-size: 17px; + font-weight: 500; + letter-spacing: -0.025em; + margin-bottom: 17px; +} +.install-command { + display: flex; + align-items: center; + gap: 8px; + width: fit-content; + max-width: 100%; + margin: 0 auto; + padding: 16px 18px; + border: 1px solid #ddd9d0; + border-radius: 6px; + background: #f2f0eb; +} +.install-command > .shell-prompt { + margin: 0 8px 0 0; + font: 14px var(--mono); +} +.install-command code { + font: 12px var(--mono); + user-select: all; + text-align: left; +} +.copy-button { + display: grid; + grid-template-columns: 17px auto; + min-height: 24px; + gap: 7px; + align-items: center; + padding: 0 0 0 19px; + margin-left: 19px; + border: 0; + border-left: 1px solid #dcd8cf; + background: transparent; + color: #6c6b62; + font-size: 11px; + white-space: nowrap; +} +.copy-button:hover { + color: var(--oxide); +} +.copy-button img { + grid-area: 1 / 1; +} +.copy-button.copied img { + visibility: hidden; +} +.copy-button.copied::after { + content: "✓"; + grid-area: 1 / 1; + color: var(--oxide); + font-size: 17px; +} +.install-note { + margin-top: 13px; + font-size: 10px; + color: #79756d; +} +.install-note span { + margin: 0 7px; +} +.quick-start { + margin-top: 28px; + font-size: 12px; +} +.quick-start pre { + width: fit-content; + margin: 14px auto; + padding-left: 16px; + border-left: 2px solid var(--line); + text-align: left; + font: 12px/1.9 var(--mono); +} +.quick-start a { + color: var(--oxide); +} +footer { + display: flex; + justify-content: space-between; + align-items: center; + padding: 27px 0 31px; + border-top: 1px solid var(--line); + font-size: 12px; +} +footer nav { + display: flex; + align-items: center; + gap: 22px; +} +footer a { + display: flex; + gap: 8px; + align-items: center; +} +footer a > span:last-child { + color: #88877e; +} +.link-divider { + width: 1px; + height: 12px; + background: #d9d5ce; +} +.handle { + color: var(--muted); +} +footer p { + color: #8b877d; + font-size: 11px; +} +@keyframes show-example { + from { + opacity: 0; + transform: translateY(6px); + } + to { + opacity: 1; + transform: none; + } +} +@keyframes change-example { + from { + opacity: 0; + } + to { + opacity: 1; + } +} +@media (max-width: 1000px) { + .page { + width: calc(100% - 48px); + } + .studio { + grid-template-columns: minmax(0, 1.15fr) minmax(0, 1fr); + } + .source { + font-size: 10px; + padding-right: 10px; + } + .line-number { + width: 35px; + padding-right: 11px; + } + .terminal-body { + padding-inline: 18px; + } + .terminal-screen { + font-size: 11px; + } +} +@media (max-width: 720px) { + .page { + width: calc(100% - 36px); + } + .site-header { + height: 80px; + } + .brand img { + width: 145px; + } + .family { + font-size: 10px; + } + .hero { + padding: 45px 0 32px; + } + .eyebrow { + font-size: 9px; + margin-bottom: 20px; + } + h1 { + font-size: clamp(34px, 6.4vw, 46px); + } + .description { + max-width: 290px; + margin: 20px auto 0; + font-size: 13px; + } + .studio { + grid-template-columns: 1fr; + } + .preview { + border-left: 0; + border-top: 1px solid #393a38; + } + .example-button { + padding: 8px 10px; + font-size: 11px; + } + .source { + min-height: 0; + padding: 19px 14px 21px 0; + font-size: 11px; + } + .line-number { + width: 36px; + } + .editor .pane-footer { + display: none; + } + .terminal-body { + padding: 21px 24px 16px; + } + .terminal-screen { + font-size: clamp(10px, 3.3vw, 13px); + } + .pane-heading { + height: 43px; + padding-inline: 17px; + } + .example-caption { + font-size: 10px; + line-height: 1.7; + margin-top: 13px; + } + .try-it { + display: block; + margin-left: 16px; + } + .installation { + padding: 36px 0; + } + h2 { + font-size: 15px; + } + .install-command { + gap: 5px; + padding: 15px 12px; + width: 100%; + } + .install-command code { + font-size: 10px; + } + .copy-button { + margin-left: auto; + padding-left: 12px; + } + .copy-button span { + position: absolute; + width: 1px; + height: 1px; + overflow: hidden; + clip-path: inset(50%); + } + footer nav { + gap: 10px; + } + footer { + flex-direction: column; + gap: 23px; + padding: 23px 0; + } +} +@media (prefers-reduced-motion: reduce) { + .example, .source, .terminal-screen { + animation: none; + } +} + +.terminal-error { + color: #ffb39f; + font-size: 11px; + line-height: 1.5; +} diff --git a/apps/landing/src/app.rs b/apps/landing/src/app.rs new file mode 100644 index 0000000..321e8ad --- /dev/null +++ b/apps/landing/src/app.rs @@ -0,0 +1,94 @@ +use crate::{examples::ExampleKind, terminal::Terminal}; +use fusor::{FromInputs, Signal, signal}; +use std::rc::Rc; +use wasm_bindgen::JsValue; + +const INSTALL: &str = "cargo install hypercmd-cli --locked"; +const COPY_SUCCESS: &str = "Copied!"; + +#[derive(Clone, Copy, PartialEq)] +struct CodeToken { + id: usize, + text: &'static str, + style: &'static str, +} + +#[derive(Clone, Copy, PartialEq)] +struct CodeLine { + number: usize, + tokens: &'static [CodeToken], +} + +#[derive(PartialEq)] +struct Example { + kind: ExampleKind, + filename: &'static str, + label: &'static str, + hint: &'static str, + rows: u16, + lines: &'static [CodeLine], +} + +include!(concat!(env!("OUT_DIR"), "/source.rs")); + +struct App { + example: Signal<&'static Example>, + clipboard: web_sys::Clipboard, + copy_label: Signal<&'static str>, +} + +impl App { + fn new() -> Result { + let window = web_sys::window().ok_or_else(|| JsValue::from_str("window is unavailable"))?; + Ok(Self { + example: signal(&EXAMPLES[0]), + clipboard: window.navigator().clipboard(), + copy_label: signal("Copy command"), + }) + } + + fn copy_install(&self) { + let promise = self.clipboard.write_text(INSTALL); + let label = self.copy_label.clone(); + wasm_bindgen_futures::spawn_local(async move { + label.set(match wasm_bindgen_futures::JsFuture::from(promise).await { + Ok(_) => COPY_SUCCESS, + Err(_) => "Select command to copy", + }); + }); + } +} + +struct Showcase { + example: &'static Example, + terminal: Rc, +} + +struct ShowcaseInputs { + example: &'static Example, +} + +impl FromInputs for Showcase { + type Inputs = ShowcaseInputs; + type Error = JsValue; + + fn from_inputs(inputs: Self::Inputs, _owner: fusor::OwnerHandle) -> Result { + Ok(Self { + example: inputs.example, + terminal: Rc::new( + Terminal::new(inputs.example.kind, inputs.example.rows) + .map_err(|error| JsValue::from_str(&error.to_string()))?, + ), + }) + } +} + +#[expect( + clippy::excessive_nesting, + reason = "generated DOM scaffolding: https://github.com/fusor-rs/fusor/issues/17" +)] +mod dom { + use super::{App, COPY_SUCCESS, EXAMPLES, INSTALL, Showcase}; + use crate::terminal::COLUMNS; + fusor::template!("web/index.html"); +} diff --git a/apps/landing/src/examples/boxes.rs b/apps/landing/src/examples/boxes.rs new file mode 100644 index 0000000..eed36cc --- /dev/null +++ b/apps/landing/src/examples/boxes.rs @@ -0,0 +1,9 @@ +use fusor::{FromInputs, Signal, signal}; + +#[derive(FromInputs)] +pub(crate) struct Boxes { + #[local(init = signal(false))] + stacked: Signal, +} + +fusor::template!(backend = "hypercmd", "ui/boxes.html"); diff --git a/apps/landing/src/examples/counter.rs b/apps/landing/src/examples/counter.rs new file mode 100644 index 0000000..7a954a2 --- /dev/null +++ b/apps/landing/src/examples/counter.rs @@ -0,0 +1,19 @@ +use fusor::{FromInputs, Signal, signal}; + +#[derive(FromInputs)] +pub(crate) struct Counter { + #[local(init = signal(0))] + count: Signal, +} + +impl Counter { + fn add(&self) { + self.count.update(|count| *count += 1); + } + + fn reset(&self) { + self.count.set(0); + } +} + +fusor::template!(backend = "hypercmd", "ui/counter.html"); diff --git a/apps/landing/src/examples/files.rs b/apps/landing/src/examples/files.rs new file mode 100644 index 0000000..3baa796 --- /dev/null +++ b/apps/landing/src/examples/files.rs @@ -0,0 +1,7 @@ +#[derive(Clone, Copy, PartialEq)] +pub(super) struct ProjectFile { + pub(super) path: &'static str, + pub(super) bytes: u64, +} + +include!(concat!(env!("OUT_DIR"), "/files.rs")); diff --git a/apps/landing/src/examples/menu.rs b/apps/landing/src/examples/menu.rs new file mode 100644 index 0000000..01d4894 --- /dev/null +++ b/apps/landing/src/examples/menu.rs @@ -0,0 +1,28 @@ +use fusor::{FromInputs, Signal, signal}; + +#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +enum Command { + Build, + Test, + Deploy, +} + +const COMMANDS: &[Command] = &[Command::Build, Command::Test, Command::Deploy]; + +impl Command { + fn label(self) -> &'static str { + match self { + Self::Build => "Build", + Self::Test => "Test", + Self::Deploy => "Deploy", + } + } +} + +#[derive(FromInputs)] +pub(crate) struct Menu { + #[local(init = signal(Command::Build))] + selected: Signal, +} + +fusor::template!(backend = "hypercmd", "ui/menu.html"); diff --git a/apps/landing/src/examples/mod.rs b/apps/landing/src/examples/mod.rs new file mode 100644 index 0000000..1fc0660 --- /dev/null +++ b/apps/landing/src/examples/mod.rs @@ -0,0 +1,27 @@ +mod boxes; +mod counter; +mod files; +mod menu; +mod search; +mod tables; + +#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +pub(crate) enum ExampleKind { + Counter, + Search, + Tables, + Boxes, + Menu, +} + +impl ExampleKind { + pub(crate) fn mount(self) -> Result { + match self { + Self::Counter => hypercmd::mount::(counter::CounterInputs), + Self::Search => hypercmd::mount::(search::SearchInputs), + Self::Tables => hypercmd::mount::(tables::TablesInputs), + Self::Boxes => hypercmd::mount::(boxes::BoxesInputs), + Self::Menu => hypercmd::mount::(menu::MenuInputs), + } + } +} diff --git a/apps/landing/src/examples/search.rs b/apps/landing/src/examples/search.rs new file mode 100644 index 0000000..f134ae9 --- /dev/null +++ b/apps/landing/src/examples/search.rs @@ -0,0 +1,21 @@ +use super::files::{FILES, ProjectFile}; +use fusor::{FromInputs, Signal, signal}; + +#[derive(FromInputs)] +pub(crate) struct Search { + #[local(init = signal(String::from(".html")))] + query: Signal, +} + +impl Search { + fn matches(&self) -> Vec { + let query = self.query.get().to_lowercase(); + FILES + .iter() + .filter(|file| file.path.contains(&query)) + .copied() + .collect() + } +} + +fusor::template!(backend = "hypercmd", "ui/search.html"); diff --git a/apps/landing/src/examples/tables.rs b/apps/landing/src/examples/tables.rs new file mode 100644 index 0000000..72b6930 --- /dev/null +++ b/apps/landing/src/examples/tables.rs @@ -0,0 +1,24 @@ +use super::files::{FILES, ProjectFile}; +use fusor::{FromInputs, Signal, signal}; + +#[derive(FromInputs)] +pub(crate) struct Tables { + #[local(init = signal(false))] + largest_first: Signal, +} + +impl Tables { + fn rows(&self) -> Vec { + let mut files: Vec<_> = FILES + .iter() + .filter(|file| file.path.ends_with(".html")) + .copied() + .collect(); + if self.largest_first.get() { + files.sort_by_key(|file| std::cmp::Reverse(file.bytes)); + } + files + } +} + +fusor::template!(backend = "hypercmd", "ui/tables.html"); diff --git a/apps/landing/src/lib.rs b/apps/landing/src/lib.rs new file mode 100644 index 0000000..4f5a3a6 --- /dev/null +++ b/apps/landing/src/lib.rs @@ -0,0 +1,3 @@ +mod app; +mod examples; +mod terminal; diff --git a/apps/landing/src/terminal.rs b/apps/landing/src/terminal.rs new file mode 100644 index 0000000..13902e1 --- /dev/null +++ b/apps/landing/src/terminal.rs @@ -0,0 +1,123 @@ +use crate::examples::ExampleKind; +use fusor::{Signal, signal}; +use hypercmd::{Error, Node, Scope, layout}; +use std::rc::Rc; +use wasm_bindgen::JsCast; + +pub(crate) const COLUMNS: u16 = 36; + +pub(crate) struct Terminal { + scope: Scope, + rows: u16, + pub(crate) error: Signal, + pub(crate) frame: Signal>, +} + +#[derive(PartialEq)] +pub(crate) struct Frame { + pub(crate) text: String, + pub(crate) buttons: Vec, + pub(crate) inputs: Vec, +} + +#[derive(Clone, PartialEq)] +pub(crate) struct TerminalControl { + pub(crate) node: Node, + pub(crate) label: String, + pub(crate) style: String, +} + +impl Terminal { + pub(crate) fn new(example: ExampleKind, rows: u16) -> Result { + let scope = example.mount()?; + scope.publish(); + let frame = signal(Rc::new(render(&scope, rows)?)); + Ok(Self { + scope, + rows, + frame, + error: signal(String::new()), + }) + } + + pub(crate) fn activate(self: &Rc, node: &Node) { + self.repaint(node.dispatch("click")); + } + + pub(crate) fn edit(self: &Rc, node: &Node, event: &web_sys::Event) { + let input = event + .target() + .expect("an input event has a target") + .dyn_into::() + .expect("text input events originate from an input element"); + self.repaint(node.edit(input.value())); + } + + fn repaint(self: &Rc, outcome: Result<(), Error>) { + if let Err(error) = outcome { + self.error.set(error.to_string()); + return; + } + let terminal = self.clone(); + // DOM handlers batch writes; paint after Hypercmd's bindings finish that batch. + wasm_bindgen_futures::spawn_local(async move { + match render(&terminal.scope, terminal.rows) { + Ok(frame) => terminal.frame.set(Rc::new(frame)), + Err(error) => terminal.error.set(error.to_string()), + } + }); + } +} + +fn render(scope: &Scope, rows: u16) -> Result { + let presentation = layout::render( + &scope.root(), + (COLUMNS, rows), + None, + &mut layout::ScrollState::default(), + &layout::LayoutOptions::default(), + )?; + let mut text = String::new(); + for row in presentation.buffer.content.chunks(usize::from(COLUMNS)) { + for cell in row { + text.push_str(cell.symbol()); + } + text.push('\n'); + } + let mut buttons = Vec::new(); + let mut inputs = Vec::new(); + for entry in presentation.entries { + match entry.node.tag() { + "button" => buttons.push(control(entry)), + "input" => inputs.push(control(entry)), + _ => {} + } + } + Ok(Frame { + text, + buttons, + inputs, + }) +} + +fn control(entry: layout::LayoutEntry) -> TerminalControl { + let rectangle = if entry.node.tag() == "input" { + entry.content + } else { + entry.rect + }; + TerminalControl { + label: entry + .node + .attribute("placeholder") + .unwrap_or_else(|| entry.node.text()), + node: entry.node, + style: format!( + concat!( + "left:{}ch;top:calc({} * var(--cell-height));", + "width:{}ch;height:calc({} * var(--cell-height))", + ), + rectangle.x, rectangle.y, rectangle.width, rectangle.height, + ), + } +} diff --git a/apps/landing/ui/boxes.html b/apps/landing/ui/boxes.html new file mode 100644 index 0000000..ed2ce91 --- /dev/null +++ b/apps/landing/ui/boxes.html @@ -0,0 +1,17 @@ + diff --git a/apps/landing/ui/counter.html b/apps/landing/ui/counter.html new file mode 100644 index 0000000..710f7bf --- /dev/null +++ b/apps/landing/ui/counter.html @@ -0,0 +1,13 @@ + diff --git a/apps/landing/ui/menu.html b/apps/landing/ui/menu.html new file mode 100644 index 0000000..1675b0d --- /dev/null +++ b/apps/landing/ui/menu.html @@ -0,0 +1,18 @@ + diff --git a/apps/landing/ui/search.html b/apps/landing/ui/search.html new file mode 100644 index 0000000..39d6688 --- /dev/null +++ b/apps/landing/ui/search.html @@ -0,0 +1,17 @@ + diff --git a/apps/landing/ui/tables.html b/apps/landing/ui/tables.html new file mode 100644 index 0000000..343bf44 --- /dev/null +++ b/apps/landing/ui/tables.html @@ -0,0 +1,20 @@ + diff --git a/apps/landing/ui/terminal.css b/apps/landing/ui/terminal.css new file mode 100644 index 0000000..b90a1e3 --- /dev/null +++ b/apps/landing/ui/terminal.css @@ -0,0 +1,37 @@ +.demo { + padding: 1ch; + gap: 1ch; + border-style: rounded; +} +.actions, .panels { + flex-direction: row; + gap: 1ch; +} +button { + min-width: 7ch; + border-style: solid; +} +label { + gap: 1ch; +} +input { + width: 24ch; +} +.results { + height: 5ch; + overflow: hidden; +} +.panels.stacked { + flex-direction: column; +} +.box { + flex-grow: 1; + padding: 1ch; + border-style: rounded; +} +.menu { + gap: 1ch; +} +.chosen { + border-style: rounded; +} diff --git a/apps/landing/web/index.html b/apps/landing/web/index.html new file mode 100644 index 0000000..e7a815e --- /dev/null +++ b/apps/landing/web/index.html @@ -0,0 +1,162 @@ + + + + + + + + + + + + hypercmd — Write CLI applications using plain HTML + + + + + + +
+ +
+
+

+ A little HTML. A whole terminal. +

+

Write CLI applications
using plain HTML

+

Your interface in HTML. Your logic in Rust. Your app in the terminal.

+
+
+
+ + + +
+ +
+

+ Same HTML. Real terminal output. + {{ state.example.get().hint }} +

+
+
+
+

Make yourself at home in the terminal.

+
+ + {{ INSTALL }} + +
+

+ macOS & Linux + Rust 1.85+ v0.1, experimental +

+
+

Create your first app:

+
hypercmd new my-app
+cd my-app
+hypercmd run
+ CLI reference +
+
+
+ +
+
+ + + + diff --git a/crates/hypercmd/Cargo.toml b/crates/hypercmd/Cargo.toml index f2d6ab4..2327e48 100644 --- a/crates/hypercmd/Cargo.toml +++ b/crates/hypercmd/Cargo.toml @@ -33,6 +33,9 @@ rustix = { workspace = true, features = ["fs", "termios"], optional = true } signal-hook = { version = "=0.3.18", default-features = false, optional = true } mio = { version = "=1.1.0", features = ["os-poll", "os-ext"], optional = true } +[target.'cfg(all(target_family = "wasm", target_os = "unknown"))'.dependencies] +web-time = "=1.1.0" + [dev-dependencies] portable-pty.workspace = true diff --git a/crates/hypercmd/src/services.rs b/crates/hypercmd/src/services.rs index d114c3e..9acdd9d 100644 --- a/crates/hypercmd/src/services.rs +++ b/crates/hypercmd/src/services.rs @@ -20,11 +20,15 @@ use std::{ atomic::{AtomicBool, AtomicUsize, Ordering}, }, task::{Context, Poll, Wake, Waker}, - time::{Duration, Instant}, + time::Duration, }; #[cfg(any(feature = "native", test))] use futures_util::stream::Stream; +#[cfg(not(all(target_family = "wasm", target_os = "unknown")))] +use std::time::Instant; +#[cfg(all(target_family = "wasm", target_os = "unknown"))] +use web_time::Instant; #[cfg(any(feature = "native", test))] const COMPLETIONS_PER_TURN: usize = 32; diff --git a/docs/async.md b/docs/async.md index 53bc105..74c905e 100644 --- a/docs/async.md +++ b/docs/async.md @@ -1,8 +1,18 @@ # Coherent async views -Hypercmd uses fusor's `AsyncBoundary`, `AsyncValue`, attempt/read-lease and source -version APIs. Declare reads with an owner and a local spawner; put loading, -error and retry controls outside the coherent region: +A coherent region doesn't show partial results. It publishes a new view only when the +reads it depends on have completed; until then it keeps the last published view on +screen. Use it when several pieces of loaded data need to appear together. See the +[restrictions](#restrictions) before placing controls inside the region. + +## Declaring an async region + +Declare reads with an owner and a local spawner, and put loading, error and retry +controls outside the coherent region. The owner is the fusor object that scopes the +lifetime of the app's state and tasks. The spawner starts the futures (Rust's values +for work that finishes later) that perform the reads. [Local services](services.md) +explains how to get a spawner from the component +owner supplied by Fusor. ```html

{{ format!("{:?}", state.boundary.status()) }}

@@ -15,50 +25,79 @@ error and retry controls outside the coherent region: ``` The state declares `boundary: fusor::coherence::AsyncBoundary` and an owned -`fusor_async::AsyncValue`. A standalone `Await` starts an independent boundary; -inside an existing coherent scope it joins that boundary. `Async` and `Await` -need a native HTML root, as in the example. Reads in independent Await branches -are discovered in the same pass. Completion of only some reads does not paint a -partial result. - -Before the first successful publication the entire region, including static -content, is hidden. Pending reads and recoverable errors retain the last -committed scene. Its event handlers are blocked until the boundary is ready. -Focus can remain on a pending control, or Tab can leave the region; completing -the read does not steal focus back from another control. Navigation and controls -outside the region remain available. - -Prepared component constructors retain their ordinary Rust semantics except -for effects explicitly deferred by `fusor::coherence::prepare_state` through -`render::construct`. Candidate effects begin only when adopted owners activate. -Arbitrary constructor side effects are not transactions. Input/structural -factories run untracked. Pending candidates survive completion and retry within -one input epoch; obsolete candidates, including slots no longer visited, are -released through `Attempt::on_invalidate`. - -Keyed rows keep committed node and component identity. Candidate reads project -row signals through `Signal::with_render_value` and `Versions`, so cached and -nested memos see speculative data without modifying committed caches. A read -can restart when captured source versions change even if its key compares equal. - -Hypercmd validates all proposed child replacements together before publishing. -Duplicate keys, duplicate component-local IDs and failed component preparation -preserve the previous scene. Publication swaps prepared values without calling -application code; afterward it updates row signals, activates adopted owners -and retires old scopes. Old event captures remain retained until this finish -phase, with scene borrows released before callbacks or destructors can run. - -Nested Async boundaries, editable controls and router outlets inside coherent -regions are unsupported. Direct authored violations produce compiler diagnostics; -incompatible reusable components fail coherent preparation while retaining the -last scene. Async regions inside routes are supported. - -`Node::is_visible()` distinguishes a hidden initial candidate from retained -content. `Node::is_interactive()` also checks owner activation, boundary readiness -and scene health. An unexpected publication fault poisons interaction for the -whole scene. Custom hosts must stop when `Scope::is_faulted()` becomes true; -the native runner restores the terminal and exits. `Scope::take_errors()` exposes -structured publication errors alongside ordinary update errors. - -The [async consumer tests](../tests/consumer/src/async_views.rs) exercise the -generated coherence contract with a controlled executor. Run `just consumer`. +`fusor_async::AsyncValue`. In the example, the status line and the Retry button sit +outside `Async`, so they stay visible and usable while the region is hidden or blocked. +`status()` reports `Detached`, `Pending`, `Ready`, `Error`, `Faulted` or `Disposed`. +`retry()` retries failed reads while allowing compatible successful reads to be reused. +For a complete Rust constructor, see `JobDetails` in the +[job inspector](../examples/job-inspector/src/main.rs). + +A standalone `Await` starts an independent boundary; inside an existing coherent scope +it joins that boundary. `Async` and `Await` each need one ordinary HTML +root element: `
` and `

` in this example. Put component tags inside that root. +Reads in independent `Await` branches are discovered in the same pass, and completion +of only some reads doesn't paint a partial result. + +## Behavior while reads are pending + +Before the first successful publication, the entire region, including static content, +is hidden. After that, pending reads and recoverable errors retain the last committed +scene (the retained tree of terminal elements), and that region's event handlers +are blocked until the boundary is ready. + +Focus can remain on a pending control, or Tab can leave the region. Completing the read +doesn't steal focus back from another control. Navigation and controls outside the +region remain available. + +## Constructors and effects + +Components in a coherent region are built as candidates before they're shown. Prepared +component constructors retain their ordinary Rust semantics, except for effects that +`fusor::coherence::prepare_state` explicitly defers through `render::construct`. +Candidate effects begin only when adopted owners activate. Arbitrary constructor side +effects are not transactions. Input/structural factories run untracked. + +Within one input epoch, pending candidates survive completion and retry. Obsolete +candidates, including slots that are no longer visited, are released through +`Attempt::on_invalidate`. + +## Keyed rows + +Keyed rows keep committed node and component identity. Candidate reads project row +signals (fusor's reactive values) through `Signal::with_render_value` and `Versions`, +so cached and nested memos (values computed from signals) see speculative data without +modifying committed caches. A read can restart when captured source versions change, even if +its key compares equal. + +## How publication works + +Hypercmd validates all proposed child replacements together before publishing. Duplicate +keys, duplicate component-local IDs and failed component preparation preserve the +previous scene. + +Publication swaps prepared values without calling application code. Afterward, in a +finish phase, it updates row signals, activates adopted owners and retires old scopes. +Old event captures remain retained until this phase, and scene borrows are released +before callbacks or destructors can run. + +## Restrictions + +Nested `Async` boundaries, editable controls and router outlets inside coherent regions +are unsupported. Direct authored violations produce compiler diagnostics; incompatible +reusable components fail coherent preparation while retaining the last scene. `Async` +regions inside routes are supported; see [terminal screens](routing.md). + +## Node and scope state for hosts + +`Node::is_visible()` distinguishes a hidden initial candidate from retained content. +`Node::is_interactive()` also checks owner activation, boundary readiness and scene +health. An unexpected publication fault disables interaction for the whole scene. + +Custom hosts must stop when `Scope::is_faulted()` becomes true; the native runner +restores the terminal and exits. `Scope::take_errors()` exposes structured publication +errors alongside ordinary update errors. + +## Verification + +The [async consumer tests](../tests/consumer/src/async_views.rs) cover the generated +coherence behavior with a controlled executor. Run `just consumer` to execute them. diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..93ac187 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,109 @@ +# CLI reference + +The `hypercmd` CLI creates, checks, runs and builds terminal applications. It +requires Rust 1.85 or newer; native applications run on macOS and Linux. + +## Install and get started + +The CLI is a Cargo package. Cargo is Rust's build tool and package manager; it comes +with the Rust toolchain and downloads dependencies, called crates, from crates.io. + +```sh +cargo install hypercmd-cli --locked +hypercmd new my-app +cd my-app +hypercmd run +``` + +`hypercmd new` checks the new package, and that first check downloads and compiles +dependencies. Edit `ui/app.html` for the interface, `ui/terminal.css` for its layout and +`src/main.rs` for state and behavior. Hypercmd doesn't watch files, so stop the app and +run `hypercmd run` again after editing. + +## hypercmd new + +```sh +hypercmd new [--hypercmd-path ] +``` + +Creates a Cargo package (a directory with a `Cargo.toml` manifest) and checks that it +compiles. The destination must not exist. The directory name becomes the package and +executable name: start with a lowercase letter and use lowercase letters, digits, +hyphens or underscores. + +The starter includes a counter, its HTML and stylesheet, a `build.rs` (Cargo's build +script, which here compiles the templates) and the required Cargo dependencies. By +default those dependencies come from crates.io. To use an unreleased local checkout: + +```sh +hypercmd new my-app --hypercmd-path /path/to/hypercmd +``` + +`--hypercmd-path` points at the repository root containing `crates/hypercmd` and +`crates/hypercmd-build`. + +## hypercmd run + +```sh +hypercmd run [ARGS]... +``` + +Builds the application in the current directory with Cargo's development profile (the +unoptimized build Cargo uses by default), then runs its executable in the terminal. +Arguments go to the application, not to Cargo. Use `--` to separate application +arguments from CLI options. + +Run it from a package with one executable. For projects with several binaries, use Cargo +directly to select one. See [native execution](native.md) for terminal sessions and +shutdown behavior. + +## hypercmd check + +```sh +hypercmd check [CARGO_ARGS]... +``` + +Runs `cargo check` and reports compiler diagnostics at the authored HTML locations +alongside Rust diagnostics. Extra arguments are forwarded to Cargo: + +```sh +hypercmd check --locked --offline +hypercmd check --manifest-path my-app/Cargo.toml +``` + +Hypercmd controls Cargo's diagnostic format; do not pass `--message-format`. + +## hypercmd build + +```sh +hypercmd build [--debug] +``` + +Builds an optimized native executable and copies it into `dist/` beside the +application's `Cargo.toml`. For a package named `my-app`, the output is `dist/my-app`. +By default, the executable targets the current host. + +`--debug` uses Cargo's development profile for a faster, unoptimized build. Run this +command from the application directory. Projects with several binaries must use Cargo +directly to choose which executable to build. + +## hypercmd profile + +```sh +hypercmd profile +``` + +Prints the supported HTML elements and CSS properties with accepted values. It doesn't +build an application. The [HTML and CSS reference](profile.md) explains layout behavior and +unsupported features. + +## Help and version + +```sh +hypercmd --help +hypercmd new --help +hypercmd --version +``` + +Every command accepts `-h` or `--help`. `-V` or `--version` prints the CLI version. +Invalid commands, build failures and other CLI errors return a nonzero exit status. diff --git a/docs/consumption.md b/docs/consumption.md index fef6642..9b2d0c7 100644 --- a/docs/consumption.md +++ b/docs/consumption.md @@ -1,52 +1,67 @@ # Independent consumption -fusor comes from crates.io, pinned to an exact version (`=0.1.4`). +A component library can share its Rust state and HTML between terminal and browser +applications, with separate styles for each. This page uses `hypercmd-job-controls` +as an example, then covers the package and browser checks for contributors. -## Cargo archives +## A shared component -`just packages` creates Cargo `.crate` archives for Hypercmd, its build -helper, the CLI and the shared component. Cargo normalizes the manifests and -removes development paths. Rust 1.85 then builds and executes a new application -in a temporary directory outside the checkout. Its only local overrides point to -extracted archives. Dependency metadata is checked to reject any path back into -a source checkout, and any dependency that does not come from crates.io. +[`hypercmd-job-controls`](../examples/job-controls) owns its Rust, HTML, `build.rs` and +separate terminal and browser styles. `JobRow` receives a memoized job (a cached value +computed from reactive state), the job +collection and a typed `Rc` inspection callback. (`Rc` is Rust's +single-threaded reference-counted pointer; the type here is a shared pointer to a +function that takes a `u32`.) Its local inspection counter survives keyed reorder. -[packages.mjs](../scripts/packages.mjs) checks package execution, styles, -dependency isolation and authored app/library diagnostics. +The [native job inspector](../examples/job-inspector) and a browser application use the +same Rust type and HTML source. -Artifacts remain under `target/package-acceptance/`: the archives, -`SHA256SUMS` and a JSON manifest with each archive's hash. The temporary -application and extracted sources are removed. Registry dependencies must already -be cached: this gate runs offline. Run `just fetch` first on a fresh -machine. +The component has two additive Cargo features, `terminal` and `browser`. A feature is an +optional compile-time switch. These two independently enable their build helpers and +generated includes, and both may be enabled in one Cargo feature union, which is what +Cargo does when different parts of a build ask for different features. The component has +no native event-loop dependency. -## A shared component +Neither `hypercmd-build` nor `fusor-build` scans a dependent package's source tree: +the library builds its own templates and ships all inputs in its archive. Browser CSS is +explicitly exported; +terminal styles are compiled into the library's generated component. + +## Cargo archives + +Hypercmd gets fusor from crates.io, pinned to an exact version (`=0.1.4`; the `=` tells +Cargo to accept only that version). + +`just packages` creates Cargo `.crate` archives, the source packages Cargo publishes, for +Hypercmd, its build helper, the CLI and the shared component. Cargo normalizes the +manifests and removes development paths. Rust 1.85 then builds and runs a new +application in a temporary directory outside the checkout. Its only local overrides point +to extracted archives. The check reads the dependency metadata and rejects any path back +into a source checkout, and any dependency that doesn't come from crates.io. -[`hypercmd-job-controls`](../examples/job-controls) owns its Rust, HTML, -`build.rs` and separate terminal/browser styles. `JobRow` receives a memoized job, -the job collection and a typed `Rc` inspection callback. Its local -inspection counter survives keyed reorder. The native job inspector and a browser application use the same Rust type and HTML source. +[packages.mjs](../scripts/packages.mjs) checks package execution, styles, dependency +isolation and authored app/library diagnostics. -Its additive `terminal` and `browser` features independently enable their build -helpers and generated includes. Both may be enabled in one Cargo feature union. -The component has no native event-loop dependency. Neither build helper crawls -a dependent package's source tree: the library builds its own templates and -ships all inputs in its archive. Browser CSS is explicitly exported; terminal -styles are compiled into the library's generated component. +Artifacts remain under `target/package-acceptance/`: the archives, `SHA256SUMS` and a +JSON manifest with each archive's hash. The temporary application and extracted sources +are removed. This check runs offline, so registry dependencies must already be cached. +Run `just fetch` first on a fresh machine. ## Browser acceptance -With Node 22+, install the Rust Wasm target, matching wasm-bindgen CLI and -Chromium, then execute the consumer: +With Rust, Node 22+ and the `just` command runner installed, run these commands +from the repository root. The setup recipe installs the Wasm targets, matching +wasm-bindgen and Fusor CLIs, npm dependencies and Chromium: ```sh just setup-browser just browser ``` -`just browser` builds the separate `tests/browser-consumer` workspace with both -component features enabled and executes it in Chromium. The [browser gate](../scripts/browser.mjs) checks the shared component's behavior -and CSS; platform coverage is listed in the [README](../README.md#platform-status). +`just browser` builds the separate `tests/browser-consumer` workspace with both component +features enabled and executes it in Chromium. The [browser script](../scripts/browser.mjs) +checks the shared component's behavior and CSS; platform coverage is listed in the +[README](../README.md#platform-status). -`just setup-browser` installs the matching fusor CLI from crates.io; `FUSOR_BIN` -can select another build of it. The browser application has its own lockfile. +`just setup-browser` installs the matching fusor CLI from crates.io; `FUSOR_BIN` can +select another build of it. The browser application has its own lockfile. diff --git a/docs/controls.md b/docs/controls.md index 3799326..8e205c1 100644 --- a/docs/controls.md +++ b/docs/controls.md @@ -1,8 +1,28 @@ # Keyboard and controls -`Controller` translates host-normalized `Input` into generated listeners. It -owns focus and the last presented geometry. Call `decorate` before output and -`presented` after output succeeds. +Hypercmd controls support keyboard navigation, text editing and mouse input. Bind them +to application state in HTML, and handle events with Rust expressions. The native runner +manages focus and input dispatch. + +## Bindings and handlers + +A signal holds a value and updates the interface when that value changes. Use `bind` +to connect a control to a signal, and `on:click` or `on:input` to handle an event. +These lines come from the [Panel component](../tests/consumer/ui/components.html): + +```html + + + +``` + +Here, `count` and `number` are numeric signals. The button increments `count`; +editing the input updates `number` before `record_input()` runs. `selection` is +`Signal>`, a reactive list of strings. Checking the box adds +`"batch"` to that list; clearing it removes the value. The component's +[Rust state](../tests/consumer/src/lib.rs) shows the field declarations. + +## Key bindings | Key | Behavior | | --- | --- | @@ -21,34 +41,48 @@ owns focus and the last presented geometry. Call `decorate` before output and | Ctrl+C | Request native shutdown | | Ctrl+Z | Request native Unix suspend | -Vertical navigation compares top-left positions, then row distance, column -distance and document order. It skips controls on the same row; Tab reaches -adjacent toolbar controls. Scrollable offscreen controls scroll into view. -Releases do not move focus; reported repeats do. Distinguishable repeat/release -reports do not activate buttons or checkboxes. - -Any container can receive focus with `tabindex="0"`; `tabindex="-1"` requires -explicit focus. Read-only text remains focusable. `autofocus` selects a control -when it first appears in a presentation. `Node::request_focus()` takes precedence -over autofocus and applies immediately when that node has presented geometry. -`Node::scroll_to(column, row)` requests an offset for the next layout; content -bounds clamp it. -Labels resolve text controls within their component instance, across structural -branches. After removal, focus moves to the next surviving control, then the -preceding control; with none available, focus clears. Keyed reorder retains -focus, draft, cursor and selection. Pointer actions use the last presented -geometry and reject disposed targets. - -Model writes do not synthesize input/change. Bindings precede authored listeners, -and each listener runs in one reactive batch. Handlers may return `()` or -`Result<(), Error>`; returned errors enter the scene's diagnostic window. -Direct events are `click` on buttons, `input` on text controls, `change` on -checkboxes, and `focus`/`blur`. Text controls emit `select` when keyboard or -pointer gestures change the caret or selection without editing the draft. -`keydown` and `scroll` visit the focused or -hit-tested target followed by its presented ancestors. `event.prevent_default()` -stops ancestor handlers and the default gesture, including Tab focus traversal. -Key releases do not dispatch `keydown`. +A grapheme is one user-perceived character, which can span several Unicode code points. + +Vertical navigation compares top-left positions, then row distance, column distance and +document order. It skips controls on the same row; Tab reaches adjacent toolbar +controls. Scrollable offscreen controls scroll into view. + +Releases don't move focus; reported repeats do. When a terminal reports repeats or +releases distinguishably, they don't activate buttons or checkboxes. + +## Focus and scrolling + +Any container can receive focus with `tabindex="0"`; `tabindex="-1"` requires explicit +focus. Text controls with `readonly` remain focusable. `autofocus` selects a control when it first +appears in a presentation. `Node::request_focus()` takes precedence over `autofocus` and +applies immediately when that node has presented geometry. +`event.target.component_root().find(id)` resolves a control in the template instance for +explicit focus requests. Labels resolve text controls within their component instance, +across structural branches. + +`Node::scroll_to(column, row)` requests an offset for the next layout; content bounds +clamp it. + +After a focused control is removed, focus moves to the next surviving control, then the +preceding control; with none available, focus clears. Keyed reorder retains focus, draft, +cursor and selection. Pointer actions use the last presented geometry and reject +disposed targets. + +## Events and handlers + +Bindings precede authored listeners, and each listener runs in one reactive batch. Model +writes don't synthesize `input` or `change` events. Handlers may return `()` (nothing) or +`Result<(), Error>`; returned errors enter the scene's diagnostic window (see +[native execution](native.md)). + +Direct events are `click` on buttons, `input` on text controls, `change` on checkboxes, +and `focus`/`blur`. `keydown` and `scroll` visit the focused or hit-tested target +followed by its presented ancestors. `event.prevent_default()` stops ancestor handlers +and the default gesture, including Tab focus traversal. Key releases do not dispatch +`keydown`. Text controls emit `select` when keyboard or pointer gestures change the +caret or selection without editing the draft. + +### Editing from Rust `Node::editor()` exposes the caret and selection as UTF-8 byte offsets at extended grapheme boundaries. `Node::replace_range(range, text)` replaces that byte range, @@ -58,19 +92,31 @@ limit return an error without changing the draft. Read-only and disabled control ignore replacements. Mouse clicks place the caret using the presented content box and retained editor scroll offsets. -`EventPayload::Input` carries the normalized `Input`, including `Modifiers` -(`shift`, `control`, `alt`, `super_key`) and vertical/horizontal scroll deltas. -`super_key` represents Command on macOS and Windows/Super elsewhere. Unhandled -Control/Alt/Super combinations do not insert text or activate controls. Ctrl+C and -Ctrl+Z remain native shutdown/suspend commands. - -`on:resize` receives `EventPayload::Resize { width, height }` after presentation, -when the node's content-box size changes. It runs once on first presentation and -lets applications size a virtual result window without depending on the host. -`event.target.component_root().find(id)` resolves a control in the template -instance for explicit focus requests. No browser event object is involved. - -See [native input](native.md) for paste normalization, byte limits and legacy -terminal behavior, and [the profile](profile.md) for Unicode policy. The -[consumer contracts](../tests/consumer/src/lib.rs) exercise generated controls, -focus and editing. +### Input payloads + +`EventPayload::Input` carries the normalized `Input`, including `Modifiers` (`shift`, +`control`, `alt`, `super_key`) and vertical/horizontal scroll deltas. `super_key` +represents Command on macOS and Windows/Super elsewhere. Unhandled Control/Alt/Super +combinations don't insert text or activate controls. Ctrl+C and Ctrl+Z remain native +shutdown/suspend commands. + +### Resize events + +`on:resize` receives `EventPayload::Resize { width, height }` after presentation, when +the node's content-box size changes. It runs once on first presentation and lets +applications size a virtual result window without depending on the host. The +[HTML and CSS reference](profile.md) describes using it to render only the visible +rows and columns of a table. No browser event object is involved. + +## Driving the controller + +`Controller` translates host-normalized `Input` into listeners and owns focus and +the last presented geometry. If you write a custom host, call `decorate` before +output and `presented` after output succeeds. The native runner does this for you. + +## See also + +See [native input](native.md) for paste normalization, byte limits and legacy terminal +behavior, and the [HTML and CSS reference](profile.md) for Unicode policy. The +[consumer tests](../tests/consumer/src/lib.rs) cover generated controls, focus and +editing. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..b9d9897 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,26 @@ +# Build terminal apps with HTML and Rust + +Hypercmd renders [Fusor](https://fusor.build/docs/) templates in terminal cells. Write +views in HTML and keep application state and behavior in Rust. Fusor provides the template +compiler and reactive state: values that update the interface when they change. + +## Get started + +Follow the [installation and first application walkthrough](../README.md#get-started). +The [CLI reference](cli.md) covers creating, checking, running and building apps. +The [HTML and CSS reference](profile.md) describes the supported HTML and CSS, and +[controls](controls.md) covers focus, keyboard input, and form bindings. + +## Build an application + +Once the first app runs, these pages cover the main areas: + +- Use [routing](routing.md) to navigate between terminal screens. +- Load data with [async views](async.md) and owner-scoped [services](services.md). +- Read [native execution](native.md) for terminal sessions and resource limits. +- Package [shared components](consumption.md) for terminal and browser consumers. + +## Status + +Hypercmd is experimental. The [status and limitations](../README.md#status-and-known-limitations) +describe the current platform support and authoring profile. diff --git a/docs/native.md b/docs/native.md index ebf5d65..3c11e04 100644 --- a/docs/native.md +++ b/docs/native.md @@ -1,93 +1,134 @@ # Native execution -See [application startup](../README.md#author-an-application) for mounting and -running a root. Disabling `native` keeps scene, controls and layout without OS I/O. +The native runner runs a Hypercmd application in a terminal on macOS and Linux. It sets up the +terminal session, decodes input, schedules local tasks and restores the terminal on exit. +See [application startup](../README.md#author-an-application) for mounting and running a +root. Disabling the `native` feature keeps scene, controls and layout without OS I/O. -`run_with(scope, &NativeOptions)` configures the required resource bounds: +## Resource limits + +`run(scope)` uses the default options. Use `run_with(scope, &NativeOptions)` to +configure the resource bounds the runner enforces: - `max_paste_bytes`: 64 KiB by default, enforced while raw paste bytes arrive. - `max_edit_bytes`: 1 MiB by default, enforced by the control editor. - `layout`: stylesheet overrides and renderable-content limits in `LayoutOptions`. -Zero input limits fail before terminal setup. The decoder holds at most 64 bytes -of an unfinished escape sequence, four bytes of an unfinished UTF-8 character, -or the paste limit plus six terminator bytes. An overflow is a visible error -returned after restoration; no partial paste or remainder executes as keys. -Invalid UTF-8 keystrokes return an error; malformed bytes inside bracketed paste -become replacement characters. [Local services](services.md) provide separate task, timer and worker -result bounds. +Zero input limits fail before terminal setup. The input decoder holds at most 64 bytes of +an unfinished escape sequence, four bytes of an unfinished UTF-8 character, or the paste +limit plus six terminator bytes. An overflow is a visible error returned after +restoration; no partial paste or remainder executes as keys. Invalid UTF-8 keystrokes +return an error; malformed bytes inside bracketed paste become replacement characters. +[Local services](services.md) provide separate task, timer and worker result bounds. ## Input and focus -See [the key table](controls.md) for focus, editing and activation. Escape is delivered to application key handlers; it has no default Back action. - -Bracketed paste is enabled for the session. A recognized paste produces one -edit; CRLF and other line breaks become spaces in single-line inputs. Textareas -normalize CRLF/CR to newlines and preserve tabs and line breaks. Embedded -Ctrl+C, Enter and escape sequences are stored as replacement characters -or spaces, so they cannot execute shortcuts. Terminals that do not report -bracketed paste fall back to ordinary key handling: unmarked paste cannot be -reliably distinguished from typing and can run shortcuts. An incomplete legacy -escape sequence expires after 40 ms. Both normal (CSI) and application (SS3) -cursor-key sequences are accepted. A bare Escape produces a key event when the -sequence deadline expires. SGR mouse reporting is enabled for pointer focus, -button activation, wheel scrolling and Shift+wheel horizontal scrolling; holding -Shift for terminal text selection depends on the emulator. The session requests the +See [the key table](controls.md) for focus, editing and activation. Escape is delivered +to application key handlers; it has no default Back action. + +### Paste + +Bracketed paste is enabled for the session: the terminal marks pasted text so the +application can tell it from typing. A recognized paste produces one edit; CRLF and other +line breaks become spaces in single-line inputs. Textareas normalize CRLF/CR to newlines +and preserve tabs and line breaks. Embedded Ctrl+C, Enter and escape sequences are stored +as replacement characters or spaces, so they cannot execute shortcuts. + +Terminals that don't report bracketed paste fall back to ordinary key handling. In that +case an unmarked paste can't be reliably distinguished from typing and can run shortcuts. + +### Keys and escape sequences + +An incomplete legacy escape sequence expires after 40 ms. Both normal (CSI) and +application (SS3) cursor-key sequences are accepted. A bare Escape produces a key event +when the sequence deadline expires. + +The session requests the [Kitty keyboard protocol's disambiguation mode](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) -and restores the previous mode on exit or suspend. Supporting terminals can -report Command/Super combinations independently of ordinary keys. A shortcut -reserved by the terminal or OS must be remapped there before the application can -receive it. Reported CSI-u modifiers and repeat/release events are decoded; -button activation ignores repeats/releases. Legacy repeats may look like -separate presses. - -The visible focus marker does not depend on color. Foreground/background colors -are disabled for `NO_COLOR` or unknown terminal capabilities. `TERM` containing -`256color` enables named/indexed colors. RGB uses `COLORTERM=truecolor` or -`24bit`; in a 256-color terminal it maps to the nearest color in the +and restores the previous mode on exit or suspend. Terminals that support it can report +Command/Super combinations independently of ordinary keys. A shortcut reserved by the +terminal or OS must be remapped there before the application can receive it. Reported +CSI-u modifiers and repeat/release events are decoded; button activation ignores +repeats/releases. Legacy repeats may look like separate presses. + +### Mouse + +SGR mouse reporting is enabled for pointer focus, button activation, wheel scrolling and +Shift+wheel horizontal scrolling. Holding Shift for terminal text selection depends on the +emulator. + +## Color and attributes + +The visible focus marker doesn't depend on color. Foreground/background colors are +disabled whenever `NO_COLOR` is set, including an empty value, or when neither +`TERM` nor `COLORTERM` indicates supported color capabilities. `TERM` containing `256color` +enables named/indexed colors. RGB colors use true color when `COLORTERM` is `truecolor` +or `24bit`; in a 256-color terminal they map to the nearest color in the [xterm color cube or grayscale ramp](https://github.com/ThomasDickey/xterm-snapshots/blob/master/256colres.h). -The first 16, theme-dependent palette entries are excluded from that mapping. Font/attribute -rendering ultimately depends on the emulator. See [the profile](profile.md) for Unicode policy. +The first 16, theme-dependent palette entries are excluded from that mapping. + +Font/attribute rendering ultimately depends on the emulator. See the +[HTML and CSS reference](profile.md) for Unicode policy. ## Terminal lifetime and scheduling +### Requirements + Interactive execution requires both stdin and stdout to be TTYs, and rejects -`TERM=dumb`; redirected output receives no screen-control sequences. Application -machine output must use a separate explicit mode. The runner uses one native -input owner, a bounded VT decoder, Crossterm for mode/output operations and -Ratatui for buffer diffing. It does not call Crossterm's event reader. - -On Unix, Mio waits for input, a signal wake socket or a task notification. At most 256 input bytes -are processed before checking shutdown, resize and painting again. A settled -application submits no frames and blocks without periodic polling. Escape -resolution and service timers use monotonic deadlines. Local futures run only -after admission or a wake; pending futures do not keep the loop polling. Native -readiness is checked between bounded task turns, including self-waking tasks. - -SIGINT, SIGTERM and SIGHUP request orderly shutdown. SIGTSTP/Ctrl+Z restores the -terminal, stops the process, then re-enters and redraws after SIGCONT. Signal -handlers only set atomic flags and wake a socket through `signal-hook`; UI work -stays on the UI thread. Modes and callback registrations are released at exit. - -The runner owns process signal handling. The upstream `signal-hook` registry -removes callbacks but does not restore an earlier/default OS signal disposition -after its last registration is removed. Use `run` as the terminal application -lifetime; a long-lived host that continues after it returns must establish its -own subsequent signal policy. Arbitrary embedding and preservation of another +`TERM=dumb`; redirected output receives no screen-control sequences. If your application +also produces machine-readable output, implement that as a separate mode that does not start +the terminal runner. + +### Scheduling + +On Unix, Mio (a Rust library for waiting on I/O events) waits for input, a signal wake +socket or a task notification. At most 256 input bytes are processed before checking +shutdown, resize and painting again. A settled application submits no frames and blocks +without periodic polling. + +Escape resolution and service timers use monotonic deadlines. Local futures run only +after admission or a wake; pending futures do not keep the loop polling. Native readiness +is checked between bounded task turns, including self-waking tasks. See +[local services](services.md) for what futures and wakes mean here. + +The runner uses one native input owner, a bounded VT decoder, Crossterm (a Rust terminal +library) for mode/output operations and Ratatui (a Rust terminal UI library) for buffer +diffing. It does not call Crossterm's event reader. + +### Signals + +In this section, signals are Unix process signals, not fusor's reactive signals. SIGINT, +SIGTERM and SIGHUP request orderly shutdown. SIGTSTP/Ctrl+Z restores the terminal, stops +the process, then re-enters and redraws after SIGCONT. Signal handlers only set atomic +flags and wake a socket through `signal-hook`; UI work stays on the UI thread. Modes and +callback registrations are released at exit. + +The runner owns process signal handling. The upstream `signal-hook` registry removes +callbacks but does not restore an earlier/default OS signal disposition (what the OS does +when a signal arrives) after its last registration is removed. Use `run` as the terminal +application lifetime; a long-lived host that continues after it returns must establish +its own subsequent signal policy. Arbitrary embedding and preservation of another library's signal-disposition ownership are not supported by this adapter. +### Restoration and errors + A session guard restores raw mode, alternate screen, cursor visibility and -bracketed-paste, mouse and keyboard modes, and closes hyperlinks on ordinary exit, -I/O errors, partial setup failure and UI panic unwinding. UI panic text is delayed -until restoration, then the panic resumes. Managed worker panics become service errors through their result future. Recoverable reactive errors preserve the committed subtree, occupy a -reserved status row and are printed with their error kind after restoration; -the diagnostic history keeps the newest 64 entries and visibly reports how many -earlier errors were omitted. Input/I/O integrity errors -terminate interaction. SIGKILL, process abort, power loss, or a disconnected -terminal cannot carry a restoration guarantee. +bracketed-paste, mouse and keyboard modes, and closes hyperlinks on ordinary exit, I/O +errors, partial setup failure and UI panic unwinding. A Rust panic interrupts normal +execution; unwinding walks back through the call stack and runs cleanup. UI panic text +is delayed until restoration, then the panic resumes. Managed worker panics become service +errors through +their result future. + +Recoverable reactive errors preserve the committed subtree, occupy a reserved status row +and are printed with their error kind after restoration. The diagnostic history keeps the +newest 64 entries and visibly reports how many earlier errors were omitted. Input/I/O +integrity errors terminate interaction. SIGKILL, process abort, power loss, or a +disconnected terminal cannot carry a restoration guarantee. ## Verification The [native PTY test](../crates/hypercmd/src/native/unix/tests.rs) checks session -restoration, input, signals, diagnostics and wake-driven services. See the +restoration, input, signals, diagnostics and wake-driven services. (A PTY is a +pseudo-terminal, which lets a test run the application as if in a real terminal.) See the [platform table](../README.md#platform-status) for coverage. diff --git a/docs/profile.md b/docs/profile.md index f96d2a9..3f7dd71 100644 --- a/docs/profile.md +++ b/docs/profile.md @@ -1,131 +1,230 @@ -# Terminal profile v1 - -`hypercmd profile` prints the element and CSS property/value table used by -validation (`hypercmd_build::profile`). Unsupported markup, control bindings, -properties, values and selector syntax fail explicitly. Rust expressions are -lowered by fusor, not rewritten by the terminal compiler. - -Containers are `main`, `section`, `div`, `ul`, `li`, `p`, `h1`–`h3`, `pre` and -`label`. Inline text supports `span`, `strong`, `em`, `br`, and `a href="…"`. Controls are -`button`, `input type="text"` (also the default type) and -`input type="checkbox"`, and `textarea`. Tables use `table`, `thead`, `tbody`, `tr`, -`th`, and `td`. See [the control reference](controls.md) for bindings and events; -static attributes are validated in [backend.rs](../crates/hypercmd-build/src/backend.rs). Document shells, browser layout repair, -media, SVG, canvas, scripts, styles in HTML, hydration and JavaScript -are rejected. Put stylesheets in package metadata. +# HTML and CSS reference + +Hypercmd accepts a fixed subset of HTML and CSS and lays it out in terminal cells. Anything +outside that subset is rejected with an error instead of being ignored. Run `hypercmd profile` +to print the same lists of elements and properties that are checked when you build. + +## Supported HTML elements {#supported-elements} + +| Elements | Purpose and terminal behavior | +| --- | --- | +| `main`, `section`, `div` | Generic containers. Children are laid out in a column by default. | +| `ul`, `li` | List container and list item. Laid out like other containers. | +| `p` | Paragraph of text. | +| `h1`, `h2`, `h3` | Headings. Rendered bold. | +| `pre` | Preformatted text. Keeps spaces, tabs and newlines and does not wrap. | +| `label` | Container for a control and its text. Children are laid out in a row by default. | +| `span` | Inline text run. Accepts text styling and `display: none` only. | +| `strong` | Inline text, bold. | +| `em` | Inline text, italic. | +| `br` | Starts a new line in text. | +| `a` | Inline link. Set its destination with `href`. | +| `button` | Clickable, focusable button. | +| `input` | Text input or checkbox: `type="text"` (the default) or `type="checkbox"`. | +| `textarea` | Multi-line text field. Three rows by default. | +| `table`, `thead`, `tbody` | Table structure. | +| `tr` | Table row. Children are laid out in a row by default. | +| `th`, `td` | Header cell (bold) and data cell. Both default to 16×1 cells, clipped and unwrapped. | + +This table lists ordinary HTML elements. Fusor component and control-flow tags, such +as `Router`, `If` and `ForEach`, are compiled separately. Other ordinary HTML elements +are unsupported. This includes document shells such as `html`, `head` and `body`, as well as +media, SVG, canvas, scripts and `style` tags in HTML. Put stylesheets in the package metadata +instead, as described below. For control attributes, bindings and events, see the +[control reference](controls.md). + +## Supported CSS properties {#exact-css-values} + +Unsupported properties and values cause a build error. Font families, margins, +positioning, grids and animations are not supported. + +| Property | Accepted values | +| --- | --- | +| `display` | `flex`, `none` | +| `flex-direction` | `row`, `column` | +| `flex-grow` | Finite number, 0 or greater | +| `flex-shrink` | Finite number, 0 or greater | +| `flex-basis` | `auto`, `0`, or a length | +| `width` | `auto`, `0`, or a length | +| `height` | `auto`, `0`, or a length | +| `min-width` | `auto`, `0`, or a length | +| `min-height` | `auto`, `0`, or a length | +| `max-width` | `auto`, `0`, or a length | +| `max-height` | `auto`, `0`, or a length | +| `gap` | One or two values, each `0` or a length | +| `row-gap` | `0` or a length | +| `column-gap` | `0` or a length | +| `padding` | One to four values, each `0` or a length | +| `padding-top` | `0` or a length | +| `padding-right` | `0` or a length | +| `padding-bottom` | `0` or a length | +| `padding-left` | `0` or a length | +| `align-items` | `flex-start`, `center`, `flex-end`, `stretch` | +| `align-self` | `auto`, `flex-start`, `center`, `flex-end`, `stretch` | +| `justify-content` | `flex-start`, `center`, `flex-end`, `space-between`, `space-around`, `space-evenly` | +| `overflow` | `visible`, `hidden`, `auto` | +| `white-space` | `normal`, `pre`, `pre-wrap` | +| `color` | A color | +| `background-color` | A color | +| `font-weight` | `bold`, `normal` | +| `font-style` | `italic`, `normal` | +| `text-decoration` | `underline`, `none` | +| `border-style` | `none`, `solid`, `rounded` | +| `border-color` | A color | + +### Lengths + +A length is a non-negative number followed by `ch` (for example `20ch`) or `%` (for example +`50%`). A bare `0` is also accepted. Percentages need a parent with a definite size; see +[units and percentages](#units-and-percentages). Units such as `px` and `em` are rejected. + +### Colors + +A color is one of: + +- `default`, which uses the terminal's own color. +- An ANSI color name: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` or `white`, + or the `bright-` version of any of these, such as `bright-red`. +- A hex value in the form `#rrggbb`, such as `#ff8800`. + +`gray` is accepted as another name for `white`. ## Stylesheets and delivery -Declare styles in the [application metadata](../README.md#author-an-application). +Declare styles in the [package metadata](../README.md#author-an-application). -Stylesheets are parsed during the package's build, in their declared order, and -embedded in its generated Rust under `OUT_DIR/fusor_backends/hypercmd/`. -Applications never read library source files at runtime. Include HTML, CSS and -`build.rs` in a library's package archive. Each generated file stores the package stylesheet once; -components reference it and selectors apply only to its nodes. Text color, emphasis -and whitespace can inherit through component boundaries. +Stylesheets are parsed during the package's build, in their declared order, and embedded +in its generated Rust under `OUT_DIR/fusor_backends/hypercmd/`. (`OUT_DIR` is the +directory Cargo gives a build script for generated files.) Applications never read +library source files at runtime. Include HTML, CSS and `build.rs` in a library's package +archive. Each generated file stores the package stylesheet once; components reference it +and selectors apply only to nodes from that package. Text color, emphasis and whitespace can +inherit through component boundaries. -Rules support a tag, `.class`, `#id`, `:focus` or `:disabled`, and compounds such -as `button.action:focus`. Comma-separated selector lists are accepted. -Specificity compares ID count, then class/pseudo count, then tag count; ties -follow source order. Whitespace combinators, attribute selectors, universal -selectors, `!important`, variables, imports, URLs and CSS functions are rejected. +### Selectors and specificity + +Rules support a tag, `.class`, `#id`, `:focus` or `:disabled`, and compounds such as +`button.action:focus`. Comma-separated selector lists are accepted. Specificity compares +ID count, then class/pseudo count, then tag count; ties follow source order. Whitespace +combinators, attribute selectors, universal selectors, `!important`, variables, imports, +URLs and CSS functions are rejected. + +### Application overrides Application overrides are explicit: set `LayoutOptions.overrides` to a compiled -stylesheet. An authored App exports `hypercmd_styles()` alongside -`hypercmd_app()` for this purpose. Overrides apply after local rules regardless -of local specificity. Merely mounting a library does not change another -component's cascade order. - -## Exact CSS values - -The validation-backed `hypercmd profile` table is authoritative: - -ANSI names are `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, -`white` and their `bright-` variants. `gray` aliases `white`. Font families, -margins, positioning, grids and animations are outside this profile. -`border-style: solid | rounded | none` draws a one-cell border, and `border-color` -accepts the same colors as text. Borders occupy layout space. Bordered automatic -scroll panes show a vertical scroll-position indicator on their right edge. - -One `ch` is one terminal cell, including one row vertically. Percentages -require a definite parent axis: the viewport, an explicit resolved size, a -stretched cross axis, or a growing item in a definite flex main axis. A -percentage against an intrinsic/indefinite parent size fails before presentation; -it does not silently become `auto`. As in the CSS sizing used by Taffy, percentage -padding on all four sides uses the parent's width. `px`, `em`, viewport and -physical units are rejected. - -Containers default to column layout; labels and table rows default to rows. -Table cells default to 16×1 cells with clipped, unwrapped content; headers are -bold. Set matching widths on `th` and `td`, or use equal flex growth for columns -that share the available width. There is no browser intrinsic column sizing or -cell spanning. Tables use ordinary retained nodes; applications can use the -content-box `resize` event to render only the visible rows and columns. Flex items default -to `flex-shrink: 0` so content remains scrollable instead of disappearing under -vertical pressure. Buttons have one cell of horizontal padding and bold labels -when enabled; authored CSS can override both. Controls inherit terminal colors -instead of assuming a dark background. Inputs default to 16×1 cells; checkboxes -to 3×1. Textareas default to three rows, preserve newlines and tabs, and scroll -the draft to keep the caret visible. Headings and -`strong` are bold, and `em` is italic. Inline runs accept text styling and -`display:none`; geometry, flex and overflow declarations on inline runs fail -with a recommendation to style a surrounding container. - -Anchors carry the complete `href` independently of the visible label. Native -output uses [OSC 8 hyperlinks](https://iterm2.com/feature-reporting/Hyperlinks_in_Terminal_Emulators.html). -A normal left click opens HTTP(S) destinations with `open` on macOS or `xdg-open` -on other Unix systems, without requiring OSC 8 support. Opener failures appear -in the diagnostic bar. Modifier-click gestures belong to the terminal emulator. -Use a non-URL label for shortened destinations: terminal auto-detection can -otherwise also open the visible text as a URL. -Clipping does not shorten the destination. Empty destinations or destinations -containing control characters or whitespace render as ordinary text. Hyperlinks -inherit through nested inline styling, and a reactive destination change updates -the link even when its label stays the same. Hosts using `layout::render` receive destinations in +stylesheet. An authored App exports `hypercmd_styles()` alongside `hypercmd_app()` for +this purpose. Overrides apply after local rules regardless of local specificity. Merely +mounting a library does not change another component's cascade order. + +## Layout and styling + +The following rules describe how the supported properties behave in terminal cells. + +### Colors and borders + +`border-style` takes `solid`, `rounded` +or `none`. `solid` and `rounded` draw a one-cell border; `none` removes it. +`border-color` accepts the same colors as text. +Borders occupy layout space. Bordered automatic scroll panes show a vertical +scroll-position indicator on their right edge. + +### Units and percentages + +One `ch` is one terminal cell, including one row vertically. Percentages require a +definite parent axis: the viewport, an explicit resolved size, a stretched cross axis, or +a growing item in a definite flex main axis. A percentage against an intrinsic/indefinite +parent size fails before presentation; it does not silently become `auto`. Percentage +padding on all four sides uses the parent's width. `px`, +`em`, viewport and physical units are rejected. + +### Layout and element defaults + +Containers default to column layout; labels and table rows default to rows. Flex items +default to `flex-shrink: 0` so content remains scrollable instead of disappearing under +vertical pressure. Buttons have one cell of horizontal padding and bold labels when +enabled; authored CSS can override both. Controls inherit terminal colors instead of +assuming a dark background. Inputs default to 16×1 cells; checkboxes to 3×1. Textareas +default to three rows, preserve newlines and tabs, and scroll the draft to keep the caret +visible. + +Headings and `strong` are bold, and `em` is italic. Inline runs accept text styling and +`display: none`; geometry, flex and overflow declarations on inline runs fail with a +recommendation to style a surrounding container. + +### Tables + +Table cells default to 16×1 terminal cells with clipped, unwrapped content; headers are +bold. Set matching widths on `th` and `td`, or use equal flex growth for columns that +share the available width. There is no browser-style intrinsic column sizing or cell +spanning. Tables use ordinary retained nodes; applications can use the content-box +`resize` event to render only the visible rows and columns. + +## Hyperlinks + +Anchors carry the complete `href` independently of the visible label, and clipping a +label does not shorten the destination. Native output uses +[OSC 8 hyperlinks](https://iterm2.com/feature-reporting/Hyperlinks_in_Terminal_Emulators.html). +A normal left click opens HTTP(S) destinations with `open` on macOS or `xdg-open` on +other Unix systems, without requiring OSC 8 support. Opener failures appear in the +diagnostic bar. Modifier-click gestures belong to the terminal emulator. + +Use a non-URL label for shortened destinations: terminal auto-detection can otherwise +also open the visible text as a URL. Empty destinations or destinations containing +control characters or whitespace render as ordinary text. Hyperlinks inherit through +nested inline styling, and a reactive destination change updates the link even when its +label stays the same. Hosts using `layout::render` receive destinations in `Presentation::hyperlinks`, indexed by each visible glyph's starting cell. ## Text, clipping and limits -`normal` collapses whitespace across adjacent inline runs and removes leading -and trailing whitespace. Indentation-only container text produces no row. -`pre` preserves spaces, tabs and newlines without wrapping. `pre-wrap` preserves -them and wraps. Wrapping occurs on extended grapheme boundaries, including across -interpolations and inline elements; a joined cluster uses the style and whitespace -policy where it starts. Tabs advance -to a four-cell stop; `br` starts a new line. Measurement and painting use the -same normalized runs. Input values and placeholders preserve spaces, stay on one -line regardless of inherited whitespace rules, and clip to the input's content -box. Button labels use authored whitespace rules; use `white-space: pre` and -`overflow: hidden` for single-row lists. - -Text uses unicode-segmentation 1.12.0 and unicode-width 0.2.0's non-CJK width -policy (ambiguous characters use one cell). Combining clusters and emoji/ZWJ -clusters remain indivisible. A clipped wide glyph is omitted as a whole; -continuation cells are cleared on each complete frame. Isolated zero-width -clusters are omitted. Terminal emulators can disagree with this width policy; -use ordinary narrow characters when exact alignment across emulators matters. - -ESC, DEL and other C0/C1 controls become the visible replacement character -U+FFFD before output. Only declared newline/tab handling is preserved. User text -cannot emit terminal control sequences. `LayoutOptions` bounds source text bytes, -visited nodes and viewport cells; exceeding a limit returns a visible error to -the runner. Structural regions count toward the visit budget. Nested layout -processing is capped at 256 levels. Zero-sized viewports produce empty buffers. - -`overflow:auto` stores scroll offsets by stable node identity, clamps them after -resize/removal and lets keyboard focus reveal a control. Painting clips against -the viewport and every clipping ancestor. Hit testing uses the last presented -layout. Full dirty frames use Ratatui's buffer diff; settled state submits no -new frames. Buttons and single-line inputs use reverse video for focus unless a -matching authored `:focus` rule supplies their appearance, including application -overrides. This keeps borders and inherited colors under the stylesheet's control. -Textareas show an underlined caret; focusable containers use authored `:focus` -styles, such as changing a rounded border to a solid border. -Controls entirely behind hidden overflow or the root viewport are excluded from -focus unless scrolling an automatic viewport can reveal them. Manual scrolling -does not reset focus visibility; resize and keyed geometry changes reveal the -focused control again. -Unsupported color/emphasis capabilities may degrade to terminal defaults; -keyboard correctness never depends on color or italic support. Emulator and -screen-reader testing status is tracked in the [platform table](../README.md#platform-status). +### Whitespace and wrapping + +With `white-space`, `normal` collapses whitespace across adjacent inline runs and removes +leading and trailing whitespace. Indentation-only container text produces no row. `pre` +preserves spaces, tabs and newlines without wrapping. `pre-wrap` preserves them and +wraps. Wrapping occurs on extended grapheme boundaries, including across interpolations +and inline elements; a joined cluster uses the style and whitespace policy where it +starts. Tabs advance to a four-cell stop; `br` starts a new line. Measurement and +painting use the same normalized runs. + +Input values and placeholders preserve spaces, stay on one line regardless of inherited +whitespace rules, and clip to the input's content box. Button labels use authored +whitespace rules; use `white-space: pre` and `overflow: hidden` for single-row lists. + +### Unicode width + +Text uses unicode-segmentation 1.12.0 and unicode-width 0.2.0's non-CJK width policy +(ambiguous characters use one cell). Combining clusters and emoji/ZWJ clusters remain +indivisible. A clipped wide glyph is omitted as a whole; continuation cells are cleared on +each complete frame. Isolated zero-width clusters are omitted. Terminal emulators can +disagree with this width policy; use ordinary narrow characters when exact alignment +across emulators matters. + +### Control characters and limits + +ESC, DEL and other C0/C1 controls become the visible replacement character U+FFFD before +output. Only declared newline/tab handling is preserved. User text cannot emit terminal +control sequences. `LayoutOptions` bounds source text bytes, visited nodes and viewport +cells; exceeding a limit returns a visible error to the runner. Structural regions count +toward the visit budget. Nested layout processing is capped at 256 levels. Zero-sized +viewports produce empty buffers. + +### Scrolling, focus and painting + +`overflow: auto` stores scroll offsets by stable node identity, clamps them after +resize/removal and lets keyboard focus reveal a control. Painting clips against the +viewport and every clipping ancestor. Hit testing uses the last presented layout. Full +dirty frames use Ratatui's buffer diff; settled state submits no new frames. + +Buttons and single-line inputs use reverse video for focus unless a matching authored +`:focus` rule supplies their appearance, including application overrides. This keeps +borders and inherited colors under the stylesheet's control. Textareas show an underlined +caret; focusable containers use authored `:focus` styles, such as changing a rounded +border to a solid border. + +Controls entirely behind hidden overflow or the root viewport are excluded from focus +unless scrolling an automatic viewport can reveal them. Manual scrolling does not reset +focus visibility; resize and keyed geometry changes reveal the focused control again. +Unsupported color/emphasis capabilities may degrade to terminal defaults; keyboard +correctness never depends on color or italic support. Emulator and screen-reader testing +status is tracked in the [platform table](../README.md#platform-status). diff --git a/docs/routing.md b/docs/routing.md index 9dc3275..8ccde88 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -1,8 +1,11 @@ # Terminal screens -`Router` and `Route` use `fusor_router::view` for route matching, decoded -parameters and nested view retention. Route factories are the compiler's supplied -factories. A terminal screen is an application location, not a network request. +Routing lets an application move between screens, such as a list and a detail view. +`Router` and `Route` use `fusor_router::view` for route matching, decoded parameters and +nested view retention. A terminal screen is an application location, not a network +request. + +## Declaring routes ```html

@@ -14,37 +17,69 @@ factories. A terminal screen is an application location, not a network request.
``` -`History::install(&owner, "/")` in the application constructor selects the -initial location. A Router without an explicit history starts at `/`. -Components resolve `History::from_owner(&owner)` and call `push`, `replace`, -`back` or `forward`. Bind these commands to application buttons; Escape is not -reserved. `location()` reads the reactive `AppUrl`, including the destination -during prepared view construction. Invalid URLs and unavailable/disposed routers -return `ErrorKind::Navigation`. - -A history retains at most 64 locations. Push after Back truncates the forward -entries; pushing beyond the limit evicts the oldest location. Back and Forward -at the ends are no-ops. History is memory-only, with no shell or browser history -integration. One root outlet uses each history; nested outlets share it. - -Destination preparation must succeed before history changes. The shared router -then commits synchronously, before a frame is presented. Failed and abandoned -stages preserve the previous location, views and focus. Reentrant history -changes return an error. Use `History` for navigation when history must stay -synchronized; directly using fusor's lower-level `Navigation` bypasses this -adapter's entries. - -Query/fragment changes preserve view identity. Changed parameters replace only -the affected view, retaining surviving parents and their local state. Focus -remains in a surviving control; otherwise the next presentation chooses the -destination's first eligible control. Candidates attached during preparation -remain invisible. History stores locations, never disposed node handles. - -A handle obtained inside a view cannot keep that view alive and becomes invalid -when it leaves. Keep a handle from the application owner for persistent navigation. -Dropping an outlet or its owner disposes the route tree even if navigation -handles remain. View-owned resources cancel through fusor ownership; work owned -by the application can continue. See [async views](async.md) for region restrictions. - -The [routing consumer](../tests/consumer/src/routing.rs) checks history and -view lifecycle; run `just consumer`. +The `:id` segment captures a path parameter. `let="job"` makes the decoded +parameters available to the template, so `/jobs/42` passes `"42"` to `JobDetails`. +The fallback displays when no route matches. The compiler supplies the factories +that construct route components. + +## Navigating + +`History::install(&owner, "/")` in the application constructor selects the initial +location. A Router without an explicit history starts at `/`. The owner is the fusor +object that scopes the application's state and tasks, and `&owner` is Rust's syntax for +borrowing it. + +Components resolve `History::from_owner(&owner)` and call `push`, `replace`, `back` or +`forward`. For example, a +component with a `history` field can navigate home with this button from the +[routing example](../tests/consumer/ui/routing.html): + +```html + +``` + +Escape is not reserved. +`location()` reads the reactive `AppUrl`, including the destination during prepared view +construction. Invalid URLs and unavailable/disposed routers return `ErrorKind::Navigation`. + +## History limits + +A history retains at most 64 locations. Push after Back truncates the forward entries; +pushing beyond the limit evicts the oldest location. Back and Forward at the ends are +no-ops. History is memory-only, with no shell or browser history integration. Each history +belongs to one root `Router`. Nested routers share it; an outlet is where a router renders its +matched view. + +## How a navigation commits + +Destination preparation must succeed before history changes. The shared router then +commits synchronously, before a frame is presented. Failed and abandoned stages preserve +the previous location, views and focus. Trying to navigate again while another navigation +is in progress returns an error. + +Use `History` for navigation when history must stay synchronized; directly using fusor's +lower-level `Navigation` bypasses this adapter's entries. + +## State and focus across navigations + +Query/fragment changes preserve view identity. Changed parameters replace only the +affected view, retaining surviving parents and their local state. Focus remains in a +surviving control; otherwise the next presentation chooses the destination's first +eligible control. Candidates attached during preparation remain invisible. History stores +locations, never disposed node handles. + +## Lifetimes and handles + +A handle obtained inside a view cannot keep that view alive and becomes invalid when it +leaves. Keep a handle from the application owner for persistent navigation. Dropping an +outlet or its owner (in Rust, letting it go out of scope and be destroyed) disposes the +route tree even if navigation handles remain. View-owned resources cancel through fusor +ownership; work owned by the application can continue. + +`Async` regions are supported inside routes, but router outlets inside coherent regions +are not. See [async views](async.md) for the region restrictions. + +## Verification + +The [routing consumer](../tests/consumer/src/routing.rs) checks history and view +lifecycle; run `just consumer`. diff --git a/docs/services.md b/docs/services.md index 359ce22..a8930c3 100644 --- a/docs/services.md +++ b/docs/services.md @@ -1,66 +1,91 @@ # Local services -Every application root installs `Services` in fusor owner context before its -constructor runs. Descendants share that instance. Obtain it with -`Services::from_owner(&owner)?`; a disposed owner cannot supply services. The -native runner drives these services. Disabling the `native` feature keeps the +`Services` gives an application a way to run local futures, timers and blocking worker +threads under Hypercmd's native runner. A future is Rust's value for work that finishes +later; it does nothing until an executor polls it, and a wake tells the executor to poll +it again. + +## Getting the services + +Every application root installs `Services` in fusor owner context before its constructor +runs. Descendants share that instance. Obtain it with `Services::from_owner(&owner)?`; a +disposed owner cannot supply services. An owner groups state and tasks that share a +lifetime, such as the contents of one screen. (The trailing `?` returns the error to the caller.) +The native runner drives these services. Disabling the `native` feature keeps the portable scene and declarations; hosts provide their own executor integration. -`services.spawner()` matches `fusor_async::Spawner`. Pass it directly to +## Async reads + +`services.spawner()` returns a function compatible with `fusor_async::Spawner`. Pass it directly to `fusor_async::AsyncValue::new`, `Resource::new` or `fusor_query::QueryClient::new`. -Fusor owns cancellation, read leases, generations and stale-result rejection. -Hypercmd schedules their local futures without moving signals or owners between -threads. `services.now()` returns monotonic elapsed `Duration` for query clocks. +Fusor owns cancellation, read leases, generations and stale-result rejection. Hypercmd +schedules their local futures without moving signals (here, fusor's reactive values) or +owners between threads. `services.now()` returns monotonic elapsed `Duration`, time +that never goes backward, for query clocks. + +## Local tasks and timers + +For other local application work, `services.spawn(&owner, future)?` waits until that +owner activates and stops polling after its disposal. This preserves prepared-candidate +timing (see [async views](async.md)). An ordinary constructor's existing effects still run +with fusor's ordinary scheduling. `services.sleep(duration)?` returns a future whose +deadline uses `Instant`; dropping it unregisters the deadline. -For other local application work, `services.spawn(&owner, future)?` waits until -that owner activates and stops polling after its disposal. This preserves -prepared-candidate timing. An ordinary constructor's existing effects still run -with fusor's ordinary scheduling. `services.sleep(duration)?` returns a future -whose deadline uses `Instant`; dropping it unregisters the deadline. +## Limits -The constructor can configure `ServiceLimits` through `set_limits`: +The constructor can configure `ServiceLimits` through `services.set_limits(limits)?`: - `max_tasks`, default 256, includes pending admissions and running local futures. - `max_timers`, default 256, bounds registered deadlines. - `max_workers`, default 4, includes unfinished workers and unconsumed results. -Zero limits and reductions below current usage return `ErrorKind::Limit` without -changing the limits. Direct admission methods return errors. Fusor's spawner has -no error return channel, so admission failure records a fatal runner error; the -native session restores before returning it. It cannot silently strand an Await. +Zero limits and reductions below current usage return `ErrorKind::Limit` without changing +the limits. Direct admission methods return errors. Fusor's spawner has no error return +channel, so admission failure records a fatal runner error; the native session restores +before returning it. An admission failure can't silently strand an Await. -The executor uses the pinned `FuturesUnordered` scheduler, which polls children -only after their wakes. A turn accepts at most the bounded incoming task set and -consumes at most 32 completions; the scheduler itself yields after polling the -live set or repeated self-wakes. Futures must return promptly from `poll`; -cooperative scheduling cannot preempt arbitrary synchronous code. Native input -and signals receive a turn even while tasks keep waking. Pending tasks alone do -not trigger periodic polling or painting. One Mio Waker handles task notifications; -the nearest timer/input deadline determines how long the runner sleeps. +## Scheduling + +Futures must return promptly from `poll`. Scheduling is cooperative, so it cannot preempt +arbitrary synchronous code. Use a [blocking worker](#blocking-workers) for work that +blocks, such as synchronous filesystem access. Native input and signals receive a turn +even while tasks keep waking. Pending tasks alone do not trigger periodic polling or painting. + +The executor uses the `FuturesUnordered` scheduler, which polls children only +after their wakes. A turn accepts at most the bounded incoming task set and consumes at +most 32 completions; the scheduler itself yields after polling the live set or repeated +self-wakes. One Mio Waker handles task notifications; the nearest timer/input deadline +determines how long the runner sleeps. ## Blocking workers -`services.worker(&token, move |cancelled| result)?` starts bounded blocking work -and returns a future yielding `Result`, where `T: Send + 'static`. -The closure receives `Arc` and should check it between operations. -Only owned input, output and that cancellation flag cross threads; `Rc`-based UI -state remains local. Application-specific errors can be carried in `T`, for -example a `Result`. - -Each admitted worker has one result slot. A completed result remains queued -until consumed or cancelled; completion and errors are not dropped to make room -for newer work. Dropping the future, cancelling its request token or disposing -the application sets the flag. A cancelled worker retains its capacity slot -until its thread exits, preventing repeated cancellations from creating -unbounded threads. The UI never joins a worker. Cancellation cannot undo writes -or forcibly interrupt a blocking library call; use cancellation-aware or bounded -I/O within the closure. +`services.worker(&token, move |cancelled| result)?` starts bounded blocking work and +returns a future yielding `Result`, where `T: Send + 'static`. `Send` means the +value can move to another thread, and `'static` rules out references that could expire +while the worker is running. The `move` keyword gives the closure ownership of what it captures. + +`token` is a `fusor_async::CancellationToken` for the request. +The closure receives `Arc`, a thread-safe flag, and should check it between +operations. Only owned input, output and that cancellation flag cross threads; `Rc`-based +UI state remains local. `Rc` shares ownership within one thread; `Arc` can share +ownership across threads. Application-specific errors can be carried in `T`, for example a +`Result`. + +Each admitted worker has one result slot. A completed result remains queued until consumed +or cancelled; completion and errors are not dropped to make room for newer work. Dropping +the future, cancelling its request token or disposing the application sets the flag. A +cancelled worker retains its capacity slot until its thread exits, preventing repeated +cancellations from creating unbounded threads. The UI never joins a worker, meaning it +never blocks the UI thread waiting for the worker to finish. Cancellation cannot undo +writes or forcibly interrupt a blocking library call; use cancellation-aware or bounded I/O +within the +closure. Worker panics become `ErrorKind::Service`. During native execution the panic hook -captures managed worker panic text, so it is reported as data through the result -instead of writing into the active terminal. Outside a native session the process -panic hook still applies. Owners and request generations decide whether a late -result is still relevant; cancellation does not authorize updating a removed UI. +captures managed worker panic text, so it is reported as data through the result instead +of writing into the active terminal. Outside a native session the process panic hook +still applies. Cancelling a worker doesn't make it safe to update UI that has been +removed; owners and request generations decide whether a late result is still relevant. ## Verification diff --git a/justfile b/justfile index 05d91dd..cec52c0 100644 --- a/justfile +++ b/justfile @@ -1,7 +1,7 @@ default: @just --list -check: lint consumer cli packages msrv +check: lint consumer cli packages msrv landing-check docs-check # A new app from the CLI must check cleanly against this checkout. cli: @@ -17,6 +17,7 @@ fetch: cargo fetch --locked cargo fetch --manifest-path tests/consumer/Cargo.toml --locked cargo fetch --manifest-path tests/browser-consumer/Cargo.toml --locked + cargo fetch --manifest-path apps/Cargo.toml --locked consumer: cargo test --manifest-path tests/consumer/Cargo.toml --locked @@ -39,6 +40,54 @@ browser: cargo clippy --manifest-path tests/browser-consumer/Cargo.toml --target wasm32-unknown-unknown --locked -- -D warnings cargo clippy -p hypercmd-job-controls --no-default-features --features browser --target wasm32-unknown-unknown --locked -- -D warnings node scripts/browser.mjs + just landing-browser + just docs-browser + just site-browser + +[working-directory: "apps"] +site: + {{env_var_or_default("FUSOR_BIN", "fusor")}} build --site --locked + +preview port="4187": + {{env_var_or_default("FUSOR_BIN", "fusor")}} preview apps/dist --port {{port}} + +[unix] +deploy environment="production": + @case "{{environment}}" in production|preview) ;; *) echo "deploy: expected production or preview, got {{environment}}" >&2; exit 2 ;; esac + vercel build {{ if environment == "production" { "--prod" } else { "" } }} --yes + find .vercel/output/static -name '.fusor-*.json' -delete + vercel deploy --prebuilt {{ if environment == "production" { "--prod" } else { "" } }} --yes + +site-browser: + node scripts/site.mjs + +docs-check: + cargo fmt --manifest-path apps/docs/Cargo.toml -- --check + cargo clippy --manifest-path apps/docs/Cargo.toml --all-targets --locked -- -D warnings + cargo +1.85 check --manifest-path apps/docs/Cargo.toml --locked + +docs: + {{env_var_or_default("FUSOR_BIN", "fusor")}} build --manifest-path apps/docs/Cargo.toml --locked + +docs-dev: + {{env_var_or_default("FUSOR_BIN", "fusor")}} dev --manifest-path apps/docs/Cargo.toml + +docs-browser: + node scripts/docs.mjs + +landing-check: + cargo fmt --manifest-path apps/landing/Cargo.toml -- --check + cargo clippy --manifest-path apps/landing/Cargo.toml --all-targets --locked -- -D warnings + cargo +1.85 check --manifest-path apps/landing/Cargo.toml --locked + +landing: + {{env_var_or_default("FUSOR_BIN", "fusor")}} build --manifest-path apps/landing/Cargo.toml --locked + +landing-dev: + {{env_var_or_default("FUSOR_BIN", "fusor")}} dev --manifest-path apps/landing/Cargo.toml + +landing-browser: + node scripts/landing.mjs setup-browser: rustup target add wasm32-unknown-unknown diff --git a/scripts/browser-app.mjs b/scripts/browser-app.mjs new file mode 100644 index 0000000..634c274 --- /dev/null +++ b/scripts/browser-app.mjs @@ -0,0 +1,57 @@ +import assert from "node:assert/strict"; +import { execFileSync, spawn } from "node:child_process"; +import { createServer } from "node:net"; +import { join, resolve } from "node:path"; +import { chromium } from "playwright"; + +export async function checkBrowser(directory, verify, buildArguments = []) { + const app = resolve(import.meta.dirname, "..", directory); + const fusor = process.env.FUSOR_BIN ?? "fusor"; + execFileSync(fusor, [ + "build", ...buildArguments, "--manifest-path", join(app, "Cargo.toml"), + "--debug", "--locked", "--offline", + ], { cwd: app, stdio: "inherit", timeout: 180_000 }); + const { server, ready, origin } = await preview(fusor, app); + let browser; + try { + await ready; + browser = await chromium.launch(); + const page = await browser.newPage(); + page.setDefaultTimeout(15_000); + const errors = []; + page.on("console", message => { + if (message.type() === "error") errors.push(message.text()); + }); + page.on("pageerror", error => errors.push(error.message)); + await verify(page, origin); + assert.deepEqual(errors, []); + } finally { + await browser?.close(); + server.kill(); + if (server.exitCode === null) await new Promise(resolve => server.once("exit", resolve)); + } +} + +async function preview(fusor, app) { + const portPicker = createServer(); + await new Promise((resolve, reject) => { + portPicker.once("error", reject); + portPicker.listen(0, "127.0.0.1", resolve); + }); + const port = portPicker.address().port; + await new Promise(resolve => portPicker.close(resolve)); + const server = spawn(fusor, ["preview", join(app, "dist"), "--port", String(port)], { cwd: app }); + const ready = new Promise((resolve, reject) => { + const timeout = setTimeout(() => reject(new Error("fusor preview did not become ready")), 10_000); + server.once("error", error => { clearTimeout(timeout); reject(error); }); + server.once("exit", code => { + clearTimeout(timeout); + reject(new Error(`fusor preview exited: ${code}`)); + }); + server.stderr.on("data", bytes => { + if (bytes.toString().includes("Ready.")) { clearTimeout(timeout); resolve(); } + }); + server.stderr.pipe(process.stderr); + }); + return { server, ready, origin: `http://127.0.0.1:${port}/` }; +} diff --git a/scripts/browser.mjs b/scripts/browser.mjs index 75807b6..c64374a 100644 --- a/scripts/browser.mjs +++ b/scripts/browser.mjs @@ -1,40 +1,9 @@ import assert from "node:assert/strict"; -import { execFileSync, spawn } from "node:child_process"; -import { dirname, join, resolve } from "node:path"; -import { createServer } from "node:net"; -import { chromium } from "playwright"; +import { checkBrowser } from "./browser-app.mjs"; -const root = resolve(import.meta.dirname, ".."); -const manifest = join(root, "tests/browser-consumer/Cargo.toml"); -const app = dirname(manifest); -const fusor = process.env.FUSOR_BIN ?? "fusor"; -execFileSync(fusor, ["build", "--manifest-path", manifest, "--debug", "--locked", "--offline"], { - cwd: app, stdio: "inherit", timeout: 180_000, -}); - -const portPicker = createServer(); -await new Promise((resolve, reject) => { portPicker.once("error", reject); portPicker.listen(0, "127.0.0.1", resolve); }); -const port = portPicker.address().port; -await new Promise(resolve => portPicker.close(resolve)); -const server = spawn(fusor, ["preview", join(app, "dist"), "--port", String(port)], { cwd: app }); -const ready = new Promise((resolve, reject) => { - const timeout = setTimeout(() => reject(new Error("fusor preview did not become ready")), 10_000); - server.once("error", error => { clearTimeout(timeout); reject(error); }); - server.once("exit", code => { clearTimeout(timeout); reject(new Error(`fusor preview exited: ${code}`)); }); - server.stderr.on("data", bytes => { if (bytes.toString().includes("Ready.")) { clearTimeout(timeout); resolve(); } }); - server.stderr.pipe(process.stderr); -}); -let browser; -try { - await ready; - browser = await chromium.launch(); - const page = await browser.newPage(); - const errors = []; - const fail = message => { errors.push(message); console.error(message); }; - page.on("console", message => { if (message.type() === "error") fail(message.text()); }); - page.on("pageerror", error => fail(error.message)); +await checkBrowser("tests/browser-consumer", async (page, origin) => { const button = (parent, name) => parent.getByRole("button", { name, exact: true }); - await page.goto(`http://127.0.0.1:${port}/`); + await page.goto(origin); const rows = page.locator(".job"); const first = rows.filter({ hasText: "Job 01" }); const second = rows.filter({ hasText: "Job 02" }); @@ -52,10 +21,5 @@ try { await button(first, "Remove").click(); assert.equal(await retained.evaluate(row => row.isConnected), false); assert.equal(await rows.count(), 1); - assert.deepEqual(errors, []); - console.log(`PASS: shared component executes local state, keyed identity, callbacks, cancel and removal in Chromium ${browser.version()}; browser/terminal outputs coexist`); -} finally { - await browser?.close(); - server.kill(); - if (server.exitCode === null) await new Promise(resolve => server.once("exit", resolve)); -} +}); +console.log("PASS: shared component state, keyed identity, callbacks, cancellation and removal"); diff --git a/scripts/docs.mjs b/scripts/docs.mjs new file mode 100644 index 0000000..a79a1f1 --- /dev/null +++ b/scripts/docs.mjs @@ -0,0 +1,67 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import { checkBrowser } from "./browser-app.mjs"; + +const root = resolve(import.meta.dirname, ".."); +const navigation = JSON.parse(await readFile(resolve(root, "apps/docs/navigation.json"), "utf8")); + +await checkBrowser("apps/docs", async (page, origin) => { + const docs = origin + "docs/"; + for (const { slug } of navigation) { + const source = `${slug || "index"}.md`; + const markdown = await readFile(resolve(root, "docs", source), "utf8"); + const title = markdown.split("\n")[0].slice(2); + await page.goto(docs + slug); + await page.getByRole("heading", { name: title, exact: true }).waitFor(); + assert.equal(await page.title(), `${title} · hypercmd`); + await checkTypography(page, slug || "index"); + const response = await page.request.get(docs + "content/" + source); + assert.equal(response.status(), 200); + assert.equal(await response.text(), markdown); + await page.setViewportSize({ width: 390, height: 844 }); + assert(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth), slug); + assert(await page.locator(".article td:first-child code").evaluateAll(nodes => + nodes.every(node => node.getClientRects().length === 1)), slug + " keeps table names intact"); + } + await page.setViewportSize({ width: 1440, height: 1000 }); + await page.goto(docs); + await page.getByRole("heading", { name: "Build terminal apps with HTML and Rust" }).waitFor(); + const profile = page.locator(".sections").getByRole("link", { name: "HTML and CSS reference" }); + assert.equal(await profile.getAttribute("href"), "/docs/profile"); + assert.equal(await page.getByRole("link", { name: "installation and first application walkthrough" }) + .getAttribute("href"), "https://github.com/fusor-rs/hypercmd/blob/main/README.md#get-started"); + await profile.click(); + await page.getByRole("heading", { name: "HTML and CSS reference", exact: true }).waitFor(); + await page.goBack(); + await page.getByRole("heading", { name: "Build terminal apps with HTML and Rust" }).waitFor(); + await page.getByRole("searchbox").fill("no-matching-topic"); + await page.locator(".search-empty").waitFor(); + await page.getByRole("searchbox").press("Escape"); + await page.getByRole("button", { name: "Toggle color theme" }).click(); + await page.reload(); + await page.locator(".site.dark").waitFor(); + await page.screenshot({ path: resolve(root, "apps/docs/target/docs-desktop.png"), fullPage: true }); + await page.setViewportSize({ width: 390, height: 844 }); + await page.getByRole("button", { name: "Toggle navigation" }).click(); + await page.locator(".sidebar").getByRole("link", { name: "Introduction" }).click(); + await page.locator(".sidebar").waitFor({ state: "hidden" }); + await page.screenshot({ path: resolve(root, "apps/docs/target/docs-mobile.png"), fullPage: true }); + await page.goto(docs + "missing"); + await page.getByRole("heading", { name: "Page not found" }).waitFor(); +}); +console.log(`PASS: ${navigation.length} Hypercmd guides, Markdown downloads, navigation and mobile layout`); + +async function checkTypography(page, slug) { + const paragraphs = await page.locator(".article .markdown p").evaluateAll(nodes => + nodes.map(node => { + const style = getComputedStyle(node); + return { size: style.fontSize, family: style.fontFamily }; + })); + assert(paragraphs.length > 1, slug + " has an introduction and body text"); + assert( + paragraphs.slice(1).every(paragraph => + paragraph.size === "14px" && paragraph.family === paragraphs[0].family), + slug + " uses the standard body typography after its introduction", + ); +} diff --git a/scripts/landing.mjs b/scripts/landing.mjs new file mode 100644 index 0000000..fc43198 --- /dev/null +++ b/scripts/landing.mjs @@ -0,0 +1,167 @@ +import assert from "node:assert/strict"; +import { readFile, stat } from "node:fs/promises"; +import { resolve } from "node:path"; +import { checkBrowser } from "./browser-app.mjs"; + +const app = resolve(import.meta.dirname, "../apps/landing"); +const examples = [ + ["Counter", "counter.html"], + ["Filesystem", "search.html"], + ["Tables", "tables.html"], + ["Boxes", "boxes.html"], + ["Menu", "menu.html"], +]; + +const interactions = { + async Counter(page, terminal) { + const increment = terminal.getByRole("button", { name: "+1", exact: true }); + await increment.click(); + await increment.focus(); + await page.keyboard.press("Enter"); + assert.match(await terminal.innerText(), /Count: 2\b/); + await terminal.getByRole("button", { name: "Reset", exact: true }).click(); + assert.match(await terminal.innerText(), /Count: 0\b/); + }, + async Filesystem(page, terminal) { + const input = terminal.getByRole("textbox", { name: "Find files" }); + for (const [query, count] of [["counter", 2], ["not-a-project-file", 0], [".HTML", 5]]) { + await input.fill(query); + assert.match(await terminal.innerText(), new RegExp(`\\b${count} matches`)); + assert.equal(await input.inputValue(), query); + assert(await input.evaluate(node => node === document.activeElement)); + } + await input.fill("counter"); + assert.match(await terminal.innerText(), /src\/examples\/counter.rs/); + assert.match(await terminal.innerText(), /ui\/counter.html/); + }, + async Tables(page, terminal) { + const files = await Promise.all(examples.map(async ([, filename]) => ({ + path: `ui/${filename}`, bytes: (await stat(resolve(app, "ui", filename))).size, + }))); + const paths = () => terminal.innerText().then(text => text.match(/ui\/[a-z]+\.html/g)); + assert.deepEqual(await paths(), files.map(file => file.path).sort()); + await terminal.getByRole("button", { name: "Sort by size" }).click(); + files.sort((left, right) => right.bytes - left.bytes || left.path.localeCompare(right.path)); + assert.deepEqual(await paths(), files.map(file => file.path)); + for (const file of files) assert((await terminal.innerText()).includes(String(file.bytes))); + }, + async Boxes(page, terminal) { + const before = await terminal.innerText(); + assert(before.split("\n").some(line => line.includes("HTML") && line.includes("Rust"))); + await terminal.getByRole("button", { name: "Toggle layout" }).click(); + const after = await terminal.innerText(); + assert(!after.split("\n").some(line => line.includes("HTML") && line.includes("Rust"))); + assert.match(after, /Markup\./); + assert.match(after, /Behavior\./); + assert((await terminal.locator(".terminal-output").innerText()).trimEnd().endsWith("╯")); + await terminal.getByRole("button", { name: "Toggle layout" }).click(); + assert.equal(await terminal.innerText(), before); + }, + async Menu(page, terminal) { + assert.match(await terminal.innerText(), /Selected: Build/); + await terminal.getByRole("button", { name: "Test", exact: true }).focus(); + await page.keyboard.press("Enter"); + assert.match(await terminal.innerText(), /Selected: Test/); + await terminal.getByRole("button", { name: "Deploy", exact: true }).click(); + assert.match(await terminal.innerText(), /Selected: Deploy/); + }, +}; + +await checkBrowser("apps/landing", async (page, origin) => { + await page.setViewportSize({ width: 1440, height: 1100 }); + await page.emulateMedia({ reducedMotion: "no-preference" }); + await page.goto(origin); + await page.getByRole("heading", { name: "Write CLI applications using plain HTML" }).waitFor(); + const picker = page.getByRole("group", { name: "Choose an example" }); + await picker.getByRole("button", { name: "Counter", exact: true }).waitFor(); + assert.deepEqual( + await picker.getByRole("button").allTextContents(), examples.map(([label]) => label), + ); + assert.equal( + await picker.getByRole("button", { name: "Counter" }).getAttribute("aria-pressed"), "true", + ); + await checkTransitions(page); + await page.emulateMedia({ reducedMotion: "reduce" }); + for (const [label, filename] of examples) { + const terminal = await select(page, label); + const source = await readFile(resolve(app, "ui", filename), "utf8"); + assert.equal(await (await page.request.get(origin + filename)).text(), source); + assert.equal((await page.locator(".code-line").allTextContents()).join("\n"), source.trimEnd()); + assert.equal(await terminal.evaluate(node => getComputedStyle(node).animationName), "none"); + await interactions[label](page, terminal); + assert((await terminal.locator(".terminal-output").innerText()).trimEnd().endsWith("╯")); + await page.screenshot({ + path: resolve(app, `target/landing-${label.toLowerCase()}.png`), fullPage: true, + }); + } + await checkInstallation(page); + for (const width of [390, 320, 768]) { + await page.setViewportSize({ width, height: 844 }); + for (const [label] of examples) { + await select(page, label); + assert( + await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth), + `${label}: ${width}px overflow`, + ); + } + const terminal = await select(page, "Counter"); + await interactions.Counter(page, terminal); + await page.screenshot({ path: resolve(app, `target/landing-${width}.png`), fullPage: true }); + } +}); +console.log( + "PASS: immediate examples, transitions, interactions, clipboard, links and responsive layout", +); + +async function select(page, label) { + await page.getByRole("group", { name: "Choose an example" }) + .getByRole("button", { name: label, exact: true }).click(); + const terminal = page.getByRole("group", { name: `Interactive terminal: ${label}`, exact: true }); + await terminal.waitFor(); + return terminal; +} + +async function checkTransitions(page) { + const entrance = await page.locator(".example").evaluate(node => + node.getAnimations().map(animation => animation.effect.getComputedTiming())); + assert(entrance.length > 0, "the example has an entrance animation"); + assert(entrance.every(timing => timing.delay === 0 && timing.endTime <= 300)); + for (const [label] of examples) { + await select(page, label); + const panes = await page.locator(".source, .terminal-screen") + .evaluateAll(nodes => nodes.map(node => { + const animations = node.getAnimations({ subtree: true }); + const timings = animations.map(animation => animation.effect.getComputedTiming()); + const rows = [...node.querySelectorAll(".source-row")]; + return { + timings, + visible: getComputedStyle(node).visibility === "visible", + complete: rows.every(row => getComputedStyle(row).opacity === "1"), + }; + })); + for (const pane of panes) { + assert(pane.timings.length > 0, label + " content has a switching animation"); + assert(pane.timings.every(timing => timing.delay === 0 && timing.endTime <= 300)); + assert(pane.visible && pane.complete, label + " shows its complete HTML and CLI together"); + } + } +} + +async function checkInstallation(page) { + await page.context().grantPermissions(["clipboard-read", "clipboard-write"]); + await page.getByRole("button", { name: "Copy command", exact: true }).click(); + await page.getByRole("button", { name: "Copied!", exact: true }).waitFor(); + assert.equal( + await page.evaluate(() => navigator.clipboard.readText()), "cargo install hypercmd-cli --locked", + ); + assert.equal( + await page.getByRole("link", { name: "Documentation" }).getAttribute("href"), "/docs/", + ); + assert.equal( + await page.getByRole("link", { name: "GitHub" }).getAttribute("href"), + "https://github.com/fusor-rs/hypercmd", + ); + assert.equal( + await page.getByRole("link", { name: /@fusor_rs/ }).getAttribute("href"), "https://x.com/fusor_rs", + ); +} diff --git a/scripts/site.mjs b/scripts/site.mjs new file mode 100644 index 0000000..6de87f5 --- /dev/null +++ b/scripts/site.mjs @@ -0,0 +1,31 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import { checkBrowser } from "./browser-app.mjs"; + +await checkBrowser("apps", async (page, origin) => { + await page.goto(origin); + await page.getByRole("heading", { name: "Write CLI applications using plain HTML" }).waitFor(); + assert.equal( + await page.locator(".quick-start pre").innerText(), + "hypercmd new my-app\ncd my-app\nhypercmd run", + ); + await page.getByRole("link", { name: "CLI reference", exact: false }).click(); + await page.getByRole("heading", { name: "CLI reference", exact: true }).waitFor(); + assert.equal(new URL(page.url()).pathname, "/docs/cli"); + await page.reload(); + await page.getByRole("heading", { name: "hypercmd new", exact: true }).waitFor(); + const markdown = await page.request.get(origin + "docs/content/cli.md"); + assert.equal(markdown.status(), 200); + assert.equal( + await markdown.text(), + await readFile(new URL("../docs/cli.md", import.meta.url), "utf8"), + ); + await page.getByRole("link", { name: "Home", exact: true }).click(); + await page.getByRole("heading", { name: "Write CLI applications using plain HTML" }).waitFor(); + await page.getByRole("link", { name: "Documentation", exact: false }).click(); + await page.getByRole("heading", { name: "Build terminal apps with HTML and Rust" }).waitFor(); + assert.equal(new URL(page.url()).pathname, "/docs/"); + await page.goto(origin + "docs/missing"); + await page.getByRole("heading", { name: "Page not found", exact: true }).waitFor(); +}, ["--site"]); +console.log("PASS: quick start, landing/docs navigation, CLI deep links and Markdown source"); diff --git a/tests/browser-consumer/Cargo.lock b/tests/browser-consumer/Cargo.lock index ab076c1..3220e54 100644 --- a/tests/browser-consumer/Cargo.lock +++ b/tests/browser-consumer/Cargo.lock @@ -354,6 +354,7 @@ dependencies = [ "taffy", "unicode-segmentation", "unicode-width 0.2.0", + "web-time", ] [[package]] @@ -838,6 +839,16 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + [[package]] name = "winnow" version = "0.7.15" diff --git a/tests/consumer/Cargo.lock b/tests/consumer/Cargo.lock index 01126fe..a125d38 100644 --- a/tests/consumer/Cargo.lock +++ b/tests/consumer/Cargo.lock @@ -29,6 +29,12 @@ dependencies = [ "generic-array", ] +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + [[package]] name = "cassowary" version = "0.3.0" @@ -378,6 +384,7 @@ dependencies = [ "taffy", "unicode-segmentation", "unicode-width 0.2.0", + "web-time", ] [[package]] @@ -459,6 +466,17 @@ version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +[[package]] +name = "js-sys" +version = "0.3.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7883d941dae510fb2d978fc3fe018c71c9e2892fd38854de3e8b92c2e5ad9cc5" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + [[package]] name = "libc" version = "0.2.189" @@ -480,6 +498,12 @@ version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + [[package]] name = "paste" version = "1.0.15" @@ -782,6 +806,61 @@ version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "wasm-bindgen" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.6", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + [[package]] name = "winnow" version = "0.7.15" diff --git a/vercel.json b/vercel.json new file mode 100644 index 0000000..e64ed3b --- /dev/null +++ b/vercel.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://openapi.vercel.sh/vercel.json", + "framework": null, + "git": { + "deploymentEnabled": false + }, + "installCommand": "", + "buildCommand": "just site", + "outputDirectory": "apps/dist", + "redirects": [ + { + "source": "/docs", + "destination": "/docs/", + "permanent": true + } + ], + "rewrites": [ + { + "source": "/docs/:path*", + "destination": "/docs/index.html" + } + ], + "headers": [ + { + "source": "/(.*)__fusor/(.*)", + "headers": [ + { + "key": "Cache-Control", + "value": "public, max-age=31536000, immutable" + } + ] + } + ] +}