",
+ "css": ".ds-palette{width:340px;overflow:hidden;border:1px solid var(--cw-border);border-radius:var(--cw-radius-xl);background:var(--cw-surface);box-shadow:0 1px 2px rgb(0 0 0 / 20%);font-family:\"Geist\", sans-serif} .ds-palette__filter{display:flex;align-items:center;gap:8px;padding:0 14px;border-bottom:1px solid var(--cw-border);color:var(--cw-text-2);transition:color var(--cw-fast)} .ds-palette__filter:focus-within{color:var(--cw-accent)} .ds-palette__filter svg{width:14px;height:14px;flex-shrink:0;fill:none;stroke:currentcolor;stroke-linecap:round;stroke-width:1.25} .ds-palette__filter input{width:100%;height:40px;border:0;outline:0;background:none;color:var(--cw-text);caret-color:var(--cw-accent);font:400 13px \"Geist\", sans-serif} .ds-palette__filter input::placeholder{color:var(--cw-text-2)} .ds-palette__rows{display:grid;gap:1px;padding:6px} .ds-row{display:grid;grid-template-columns:6px auto minmax(0,1fr) auto;align-items:center;gap:8px;width:100%;padding:7.6px 8px;border:0;border-radius:var(--cw-radius-m);background:none;color:var(--cw-text-2);font:400 13px \"Geist\", sans-serif;text-align:left;cursor:pointer;transition:color var(--cw-fast),background-color var(--cw-fast)} .ds-row:hover,.ds-row.is-on{background:var(--cw-elevated);color:var(--cw-text)} .ds-row:focus-visible{outline:1px solid var(--cw-accent);outline-offset:-1px} .ds-row i{display:inline-block;width:6px;height:6px;border-radius:1px;background:var(--cw-muted)} .ds-row.is-on i{background:var(--cw-accent)} .ds-row b{font-weight:500} .ds-row code{color:var(--cw-text-2);font:400 11px \"Geist Mono\", monospace} .ds-tag{padding:0 4px;border:1px solid var(--cw-border);border-radius:var(--cw-radius-s);font:400 10px/16px \"Geist Mono\", monospace} .ds-tag--cli{border-color:color-mix(in srgb,var(--cw-purple) 34%,transparent);color:var(--cw-purple)} .ds-palette__hints{display:flex;gap:16px;padding:8px 14px;border-top:1px solid var(--cw-border);color:var(--cw-text-2);font-size:11px} .ds-palette__hints kbd{display:inline-block;min-width:17px;padding:0 3.6px;border:1px solid var(--cw-border);border-radius:var(--cw-radius-s);background:var(--cw-elevated);color:var(--cw-text-2);font:400 10px/16px \"Geist Mono\", monospace;text-align:center}"
+ },
+ {
+ "name": "Status Bar",
+ "kind": "custom",
+ "description": "The footer's last row. Alpha state on the left in Geist Mono with an amber square, links on the right.",
+ "html": "
alphaIndependent project. Not affiliated with Cloudflare.Discord
",
+ "css": ".ds-status{display:flex;flex-wrap:wrap;align-items:center;gap:3px 16px;padding:7px 16px;border-top:1px solid var(--cw-border);background:var(--cw-bg);color:var(--cw-text-2);font:400 11px/1.5 \"Geist\", sans-serif} .ds-status__state{display:inline-flex;align-items:center;gap:5px;color:var(--cw-text);font-family:\"Geist Mono\", monospace} .ds-status__state i{display:inline-block;width:6px;height:6px;border-radius:1px;background:var(--cw-amber)} .ds-status__end{margin-left:auto} .ds-status a{color:var(--cw-text-2);transition:color var(--cw-fast)} .ds-status a:hover{color:var(--cw-text)} .ds-status a:focus-visible{outline:1px solid var(--cw-accent);outline-offset:2px}"
+ }
+ ],
+ "narrative": {
+ "northStar": "The Native Utility",
+ "overview": "The docs behave like one developer tool that a reader already has open. Slim chrome, keyboard shortcuts shown as keycaps, a status bar for a footer, and search that opens as a command palette all come from native desktop tooling. Real code is the main visual material, and the home page previews it inside a package palette.\n\nThe system is dark only and dense. Three graphite steps and 1px borders carry all structure. Colour appears in small amounts, and each colour has a job. Tiny square markers show position and state, so no icon set or illustration is needed beyond the puffin logo in the header.\n\nThe world rejects the SaaS landing page, meaning a hero with a mascot and a grid of feature cards. The site runs on MkDocs Material, and every token maps onto Material's variables, so generated API pages inherit the same look.",
+ "keyCharacteristics": [
+ "Dark only, with no theme toggle.",
+ "Geist for text and chrome, Geist Mono for anything a developer would type or read as a machine value.",
+ "1px borders and tonal steps instead of shadows at rest.",
+ "Square markers, compact rectangular badges and keycaps.",
+ "A 140ms state transition on almost every interactive element."
+ ],
+ "rules": [
+ {
+ "name": "The Label Ground Rule",
+ "body": "Label Grey sits on Graphite Ground only. Small text on a panel or a raised step uses Secondary Grey, because Label Grey drops below 4.5:1 there.",
+ "section": "colors"
+ },
+ {
+ "name": "The Decoration Rule",
+ "body": "Decoration Grey never carries information a reader needs to read. If removing it would lose meaning, the element needs Secondary Grey.",
+ "section": "colors"
+ },
+ {
+ "name": "The Purple Rule",
+ "body": "Purple means a command, the CLI, or a Python keyword. Links and buttons stay teal or neutral.",
+ "section": "colors"
+ },
+ {
+ "name": "The Mono Rule",
+ "body": "Geist Mono is for code, commands, shortcuts, statuses and identifiers. Everything else, including every label a person wrote, is Geist.",
+ "section": "typography"
+ },
+ {
+ "name": "The Root Rule",
+ "body": "The html element is pinned at 125%, which is 20px at the browser default, and Material's wide-screen growth is off. So .05rem is 1px, and every rem value in this file assumes that root.",
+ "section": "typography"
+ },
+ {
+ "name": "The Float Rule",
+ "body": "A shadow means the element sits above the page. Panels in the document flow, including the header, stay flat.",
+ "section": "elevation"
+ },
+ {
+ "name": "The Square Rule",
+ "body": "State is marked with a tiny square, not a dot, stripe or icon. Teal is current, Decoration Grey is idle, amber is a warning or alpha status.",
+ "section": "shapes"
+ }
+ ],
+ "dos": [
+ "Do keep the page dark, using only the three graphite steps for grounds.",
+ "Do use 1px Hairline borders (#34373b) and thin rules to separate things.",
+ "Do set commands, shortcuts, statuses, package names and file names in Geist Mono.",
+ "Do mark the current item with a 5px or 6px teal square.",
+ "Do show a keycap only when the shortcut works.",
+ "Do write rem values against the 20px root, where .05rem is 1px.",
+ "Do use Secondary Grey (#92979e) for small text on Panel Graphite or Raised Graphite.",
+ "Do map new colours through the `--cw-*` tokens and Material's `--md-*` variables, so generated API pages inherit them."
+ ],
+ "donts": [
+ "Don't add a light theme or a theme toggle.",
+ "Don't build a hero with a mascot or a grid of feature cards. The puffin stays in the header as the logo.",
+ "Don't use Decoration Grey (#686d74) for text a reader needs.",
+ "Don't put Label Grey (#7f858c) on Panel Graphite or Raised Graphite.",
+ "Don't use purple for links, buttons or general emphasis.",
+ "Don't raise amber's saturation, or use it for anything other than warnings, alpha status and syntax values.",
+ "Don't divide page sections with background bands.",
+ "Don't put a shadow on a panel in the document flow, other than the palette's contact shadow.",
+ "Don't set uppercase or tracked labels in HTML chrome.",
+ "Don't use radii above 10px, or pill shapes."
+ ]
+ }
+}
diff --git a/.impeccable/review/api-d.png b/.impeccable/review/api-d.png
new file mode 100644
index 0000000..3a32c38
Binary files /dev/null and b/.impeccable/review/api-d.png differ
diff --git a/.impeccable/review/desktop.png b/.impeccable/review/desktop.png
new file mode 100644
index 0000000..e32e720
Binary files /dev/null and b/.impeccable/review/desktop.png differ
diff --git a/.impeccable/review/guide-d.png b/.impeccable/review/guide-d.png
new file mode 100644
index 0000000..ff67c5e
Binary files /dev/null and b/.impeccable/review/guide-d.png differ
diff --git a/.impeccable/review/guide-m.png b/.impeccable/review/guide-m.png
new file mode 100644
index 0000000..c8ef50c
Binary files /dev/null and b/.impeccable/review/guide-m.png differ
diff --git a/.impeccable/review/home-d.png b/.impeccable/review/home-d.png
new file mode 100644
index 0000000..06f2b96
Binary files /dev/null and b/.impeccable/review/home-d.png differ
diff --git a/.impeccable/review/mobile.png b/.impeccable/review/mobile.png
new file mode 100644
index 0000000..92fa083
Binary files /dev/null and b/.impeccable/review/mobile.png differ
diff --git a/.impeccable/review/search.png b/.impeccable/review/search.png
new file mode 100644
index 0000000..b212987
Binary files /dev/null and b/.impeccable/review/search.png differ
diff --git a/.impeccable/surfaces/docs.md b/.impeccable/surfaces/docs.md
new file mode 100644
index 0000000..2f4cb5a
--- /dev/null
+++ b/.impeccable/surfaces/docs.md
@@ -0,0 +1,20 @@
+---
+version: 1
+slug: "docs"
+primary_target: "docs"
+related_targets: []
+---
+
+Scope: docs home page and every doc page (MkDocs Material). Mode: Read.
+Reader: Python developer evaluating Crosswind. Job: see packages and code, pick one, start.
+Constraints: keep content and generated API pages. Dark only. Keep the diagram, drop the mascot. Restyle Material search with Ctrl+K.
+
+## Direction contract
+
+THESIS: The docs behave like one native developer utility. Refuses the SaaS hero with a mascot and a feature-card grid.
+OWN-WORLD: User-pinned palette #191B1D, #202225, #282B2E, #34373B, #E6E7E8, #92979E, #686D74, accent #67CDBB, muted purple for CLI. Geist and Geist Mono. 1px borders, 8px radii, tiny square markers, compact rectangular badges, keycaps.
+STORY: The reader learns what Crosswind is, previews each package's real code in a palette, opens that package's docs, and reads a calm column framed by native chrome.
+FIRST VIEWPORT: Slim header and package tabs. Left: 44px H1, one paragraph, buttons, command with copy, alpha line. Right: small inspector of facts. Below at full grid width: the package palette with filter and rows on the left, code preview on the right.
+FORM: Pinned by the brief, so no roll ran. Position: user-pinned. Seed key: none.
+Signature interaction: filter and arrow through packages, code preview swaps, Enter opens docs. Status bar footer, P and N page shortcuts shown as keycaps.
+FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, DESIGN.md, and every shipping raster carrying its provenance
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..89d67a9
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,368 @@
+---
+name: Crosswind
+description: Docs for typed, async Python SDKs on Cloudflare Workers, built to behave like one native developer utility.
+colors:
+ bg: "#191b1d"
+ surface: "#202225"
+ elevated: "#282b2e"
+ border: "#34373b"
+ border-strong: "#484c51"
+ text: "#e6e7e8"
+ text-2: "#92979e"
+ label: "#7f858c"
+ muted: "#686d74"
+ accent: "#67cdbb"
+ purple: "#a99fd6"
+ amber: "#d0ae74"
+ red: "#d98a82"
+ code-function: "#b9d4e6"
+typography:
+ display:
+ fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif"
+ fontSize: "2.1rem"
+ fontWeight: 600
+ lineHeight: 1.08
+ letterSpacing: "-0.034em"
+ headline:
+ fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif"
+ fontSize: "1.5rem"
+ fontWeight: 600
+ lineHeight: 1.15
+ letterSpacing: "-0.028em"
+ title:
+ fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif"
+ fontSize: "1rem"
+ fontWeight: 600
+ lineHeight: 1.3
+ letterSpacing: "-0.016em"
+ subtitle:
+ fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif"
+ fontSize: "0.8rem"
+ fontWeight: 600
+ lineHeight: 1.4
+ letterSpacing: "-0.008em"
+ body:
+ fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif"
+ fontSize: "0.75rem"
+ fontWeight: 400
+ lineHeight: 1.65
+ chrome:
+ fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif"
+ fontSize: "0.625rem"
+ fontWeight: 400
+ lineHeight: 1.35
+ label:
+ fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif"
+ fontSize: "0.55rem"
+ fontWeight: 500
+ lineHeight: 1.35
+ code:
+ fontFamily: "Geist Mono, SFMono-Regular, Consolas, Menlo, monospace"
+ fontSize: "0.625rem"
+ fontWeight: 400
+ lineHeight: 1.6
+ mono-label:
+ fontFamily: "Geist Mono, SFMono-Regular, Consolas, Menlo, monospace"
+ fontSize: "0.55rem"
+ fontWeight: 400
+ lineHeight: 1.5
+ mono-micro:
+ fontFamily: "Geist Mono, SFMono-Regular, Consolas, Menlo, monospace"
+ fontSize: "0.5rem"
+ fontWeight: 400
+ lineHeight: "0.8rem"
+rounded:
+ marker: "1px"
+ s: "4px"
+ m: "6px"
+ l: "8px"
+ xl: "10px"
+spacing:
+ xs: "0.2rem"
+ s: "0.3rem"
+ m: "0.4rem"
+ l: "0.6rem"
+ xl: "0.8rem"
+ 2xl: "1.4rem"
+components:
+ button:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.text}"
+ typography: "{typography.chrome}"
+ rounded: "{rounded.m}"
+ padding: "0.28rem 0.65rem"
+ button-hover:
+ backgroundColor: "{colors.elevated}"
+ textColor: "{colors.text}"
+ button-primary:
+ backgroundColor: "color-mix(in srgb, #67cdbb 14%, #191b1d)"
+ textColor: "{colors.accent}"
+ typography: "{typography.chrome}"
+ rounded: "{rounded.m}"
+ padding: "0.28rem 0.65rem"
+ button-primary-hover:
+ backgroundColor: "color-mix(in srgb, #67cdbb 20%, #191b1d)"
+ textColor: "{colors.accent}"
+ input-search:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.text}"
+ typography: "{typography.chrome}"
+ rounded: "{rounded.m}"
+ height: "1.4rem"
+ width: "11rem"
+ input-search-open:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.text}"
+ rounded: "{rounded.xl}"
+ height: "2rem"
+ width: "34rem"
+ nav-link:
+ textColor: "{colors.text-2}"
+ typography: "{typography.chrome}"
+ rounded: "{rounded.m}"
+ padding: "0.2rem 0.4rem 0.2rem 0.7rem"
+ nav-link-hover:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.text}"
+ nav-link-active:
+ backgroundColor: "{colors.elevated}"
+ textColor: "{colors.text}"
+ badge:
+ textColor: "{colors.text-2}"
+ typography: "{typography.mono-micro}"
+ rounded: "{rounded.s}"
+ padding: "0 0.2rem"
+ badge-cli:
+ textColor: "{colors.purple}"
+ typography: "{typography.mono-micro}"
+ rounded: "{rounded.s}"
+ padding: "0 0.2rem"
+ keycap:
+ backgroundColor: "{colors.elevated}"
+ textColor: "{colors.text-2}"
+ typography: "{typography.mono-micro}"
+ rounded: "{rounded.s}"
+ padding: "0 0.18rem"
+ inline-code:
+ backgroundColor: "{colors.surface}"
+ rounded: "{rounded.s}"
+ padding: "0.08em 0.32em"
+ code-panel:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.text}"
+ typography: "{typography.code}"
+ rounded: "{rounded.l}"
+ padding: "0.65rem 0.8rem"
+ callout:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.text}"
+ rounded: "{rounded.l}"
+ padding: "0.5rem 0.7rem"
+ command:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.purple}"
+ typography: "{typography.code}"
+ rounded: "{rounded.m}"
+ palette:
+ backgroundColor: "{colors.surface}"
+ textColor: "{colors.text}"
+ rounded: "{rounded.xl}"
+ palette-row:
+ textColor: "{colors.text-2}"
+ rounded: "{rounded.m}"
+ padding: "0.38rem 0.4rem"
+ palette-row-selected:
+ backgroundColor: "{colors.elevated}"
+ textColor: "{colors.text}"
+---
+
+# Design System: Crosswind
+
+## Overview
+
+**Creative North Star: "The Native Utility"**
+
+The docs behave like one developer tool that a reader already has open. Slim chrome, keyboard shortcuts shown as keycaps, a status bar for a footer, and search that opens as a command palette all come from native desktop tooling. Real code is the main visual material, and the home page previews it inside a package palette.
+
+The system is dark only and dense. Three graphite steps and 1px borders carry all structure. Colour appears in small amounts, and each colour has a job. Tiny square markers show position and state, so no icon set is needed. The only illustrations are the puffin logo in the header and the package diagram.
+
+The world rejects the SaaS landing page, meaning a generic hero and a grid of feature cards. The site runs on MkDocs Material, and every token maps onto Material's variables, so generated API pages inherit the same look.
+
+**Key Characteristics:**
+- Dark only, with no theme toggle.
+- Geist for text and chrome, Geist Mono for anything a developer would type or read as a machine value.
+- 1px borders and tonal steps instead of shadows at rest.
+- Square markers, compact rectangular badges and keycaps.
+- A 140ms state transition on almost every interactive element.
+
+## Colors
+
+Near-neutral graphite with a cool cast, one teal accent, and two quiet secondary hues with narrow jobs. The palette is user-pinned. Label Grey and amber are added steps.
+
+### Primary
+- **Terminal Teal** (#67cdbb): Marks where the reader is and what they can act on. It colours links, the primary button, the active square marker, the focus ring, search matches, the text caret and code strings. Tints use `color-mix` at 10% to 42%.
+
+### Secondary
+- **Muted Command Purple** (#a99fd6): The colour of commands and the CLI badge. Python keywords in code use it as a secondary use.
+
+### Tertiary
+- **Low-Saturation Red** (#d98a82): An added danger colour, used only on danger, error and failure callouts.
+- **Low-Saturation Amber** (#d0ae74): An added warning colour. It marks warning and caution callouts, quote callout labels, and the alpha status. Syntax highlighting also uses it for numbers, constants and builtins.
+
+### Neutral
+- **Graphite Ground** (#191b1d): The page, header, tabs, footer and sidebars.
+- **Panel Graphite** (#202225): Code panels, callouts, the palette, inline code, default buttons and the sidebar hover.
+- **Raised Graphite** (#282b2e): Title bars of code panels, keycaps, the selected row and the active sidebar link.
+- **Hairline** (#34373b): Every resting border and divider.
+- **Hover Hairline** (#484c51): Borders on hover, and on open search and the diagram tooltip.
+- **Soft White** (#e6e7e8): Headings, body text and the current item.
+- **Secondary Grey** (#92979e): Secondary text at any size, on any of the three graphite steps. Idle navigation, captions, table headers and code comments use it.
+- **Label Grey** (#7f858c): An added step for small labels, such as sidebar section names and the fact table's terms. It reaches 4.64:1 on Graphite Ground, 4.28:1 on Panel Graphite and 3.82:1 on Raised Graphite.
+- **Decoration Grey** (#686d74): Decoration only, because it fails 4.5:1 on every step (3.31:1 on Graphite Ground). Use it for command prompts, breadcrumb separators, idle square markers and unchecked task boxes.
+- **Pale Function Blue** (#b9d4e6): Function names in syntax highlighting. It appears nowhere else.
+
+### Named Rules
+**The Label Ground Rule.** Label Grey sits on Graphite Ground only. Small text on a panel or a raised step uses Secondary Grey, because Label Grey drops below 4.5:1 there.
+
+**The Decoration Rule.** Decoration Grey never carries information a reader needs to read. If removing it would lose meaning, the element needs Secondary Grey.
+
+**The Purple Rule.** Purple means a command, the CLI, or a Python keyword. Links and buttons stay teal or neutral.
+
+## Typography
+
+**Display Font:** Geist (with -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif)
+**Body Font:** Geist (with the same fallback)
+**Label/Mono Font:** Geist Mono (with SFMono-Regular, Consolas, Menlo, monospace)
+
+**Character:** One neutral grotesque carries headings, prose and chrome, tightened as sizes grow. Geist Mono separates machine values from prose at the same small sizes. The site loads Geist at 400, 500 and 600, and Geist Mono at 400 and 500.
+
+### Hierarchy
+
+Sizes are rem at a 20px root. Pixel values below are the rendered result.
+
+- **Display** (600, 42px, 1.08): The home page heading only. It drops to 32px at 960px wide and below. The direction contract asked for 44px, and the build ships 42px.
+- **Headline** (600, 30px, 1.15): The H1 of each doc page.
+- **Title** (600, 20px, 1.3): H2 sections, each under a 1px top rule.
+- **Subtitle** (600, 16px, 1.4): H3, and the label column on home page sections. H4 is 14px in Secondary Grey.
+- **Body** (400, 15px, 1.65): Prose, capped at 72ch. The home lede is 16px at 1.55 in Secondary Grey. Callouts are 14px.
+- **Chrome** (400, 12.5px, 1.35): Tabs, sidebar links, buttons and the search input. Active items step up to 500. Tables are 13px with 12px headers.
+- **Label** (500, 11px): Sidebar section names and small captions. Sentence case, no tracking.
+- **Code** (Geist Mono 400, 12.5px, 1.6): Code panels with tabular numerals and no ligatures. Inline code is 0.84em.
+- **Mono label** (Geist Mono 400, 11px, 1.5): File names, callout labels and the copied toast.
+- **Mono micro** (Geist Mono 400, 10px): Badges and keycaps.
+
+### Named Rules
+**The Mono Rule.** Geist Mono is for code, commands, shortcuts, statuses and identifiers. Everything else, including every label a person wrote, is Geist.
+
+**The Root Rule.** The html element is pinned at 125%, which is 20px at the browser default, and Material's wide-screen growth is off. So .05rem is 1px, and every rem value in this file assumes that root.
+
+## Layout
+
+The main grid is capped at 66rem (1320px). On doc pages the primary sidebar is 11rem (220px), the secondary sidebar is 10rem (200px), and the content column is capped at 42rem (840px) from 1220px wide. Code and tables take the column's full width while prose keeps its 72ch measure.
+
+The home hero is a text column beside a 16rem (320px) fact table with a 3rem gap, aligned to the bottom edge. The palette below it takes the full grid width, with a 17rem (340px) side column. Later home sections use a 13rem (260px) label column with the heading absolutely placed in it.
+
+Spacing clusters on 4, 6, 8, 12 and 16px. The 0.8rem (16px) inset is the standard horizontal padding for panels, title bars and result rows. Rows stay compact, with 0.2rem to 0.4rem of vertical padding.
+
+Hero, palette and section columns collapse to one at 960px. The sidebars become Material's drawer below 1220px, where each link grows to 14px with 0.5rem of vertical padding. On the home page, the packages table turns into a stack of rows at 960px. The diagram's caption text moves out of the scene at 720px.
+
+## Elevation & Depth
+
+The system is flat and tonal. Depth comes from the three graphite steps and 1px borders, so a raised thing is lighter and a title bar is one step above its panel. Page sections divide with a thin rule, never with a background band.
+
+### Shadow Vocabulary
+- **Float** (`box-shadow: 0 8px 24px rgb(0 0 0 / 28%)`): Elements that float above the page, which are open search, the copied toast and the diagram tooltip.
+- **Palette contact** (`box-shadow: 0 1px 2px rgb(0 0 0 / 20%)`): The package palette at rest. It is the only resting shadow.
+
+Open search also dims the page behind it with `rgb(12 13 14 / 64%)`.
+
+### Named Rules
+**The Float Rule.** A shadow means the element sits above the page. Panels in the document flow, including the header, stay flat.
+
+## Shapes
+
+Small, even radii on rectangles. There are four steps: 4px for badges, keycaps and inline code, 6px for buttons, nav links, and the search field, 8px for panels and tables, and 10px for the largest containers, which are the palette, open search and the diagram. The contract named 8px radii, and the build added the other steps around it. Square markers are 5px or 6px with a 1px radius. All strokes are 1px, and panels clip their contents with `overflow: hidden`.
+
+### Named Rules
+**The Square Rule.** State is marked with a tiny square, not a dot, stripe or icon. Teal is current, Decoration Grey is idle, amber is a warning or alpha status.
+
+## Components
+
+Components are quiet and tool-like. State changes are colour, border or background shifts at 140ms. Palette pane entry and diagram messages ease with `cubic-bezier(0.23, 1, 0.32, 1)`. `prefers-reduced-motion` turns transitions and the pane animation off. Focus everywhere is a 1px teal outline with a 2px offset.
+
+### Buttons
+- **Shape:** Gently rounded rectangle (6px) with a 1px border.
+- **Primary:** Teal text on a 14% teal tint of Graphite Ground, with a 42% teal border. It does not fill solid.
+- **Default:** Soft White on Panel Graphite with a Hairline border.
+- **Hover / Focus:** Default moves to Raised Graphite and Hover Hairline. Primary moves to a 20% tint and a 70% border.
+- **Active:** Opacity 0.75.
+
+### Badges and keycaps
+- **Badge:** Mono micro text in a 4px outlined rectangle with no fill, reading SDK or CLI. The CLI badge is purple with a 34% purple border.
+- **Keycap:** Mono micro text on Raised Graphite with a Hairline border and no shadow. It labels real shortcuts only, which are Ctrl K, the arrows, Enter, Esc, and P and N on the previous and next links, shown only to hover-capable pointers.
+
+### Cards / Containers
+- **Corner Style:** 8px for code panels, callouts, tables and previous and next links.
+- **Background:** Panel Graphite, with title bars on Raised Graphite.
+- **Shadow Strategy:** Flat, as in Elevation & Depth.
+- **Border:** 1px Hairline, moving to Hover Hairline on interactive panels.
+- **Internal Padding:** 0.65rem by 0.8rem in code, 0.5rem by 0.7rem in callouts.
+
+### Inputs / Fields
+- **Style:** The search field is a 1.4rem tall Panel Graphite field with a 6px radius and a keycap at its right edge. The palette filter is borderless inside its own row.
+- **Focus:** The search border moves to Hover Hairline, and the palette filter icon turns teal. Inputs drop the global focus ring because the container shows focus. The caret is teal.
+- **Open search:** Ctrl K or Cmd K opens a centred 34rem field at 14vh, 2rem tall with a 10px radius. Once a query exists, it joins the results as one panel. Each result is one title and one line of context, with a hint row of keycaps underneath.
+
+### Navigation
+- **Header and tabs:** Two thin rows on Graphite Ground, each with a 1px bottom border and no shadow. The repository name is Geist Mono.
+- **Tabs:** 12.5px Secondary Grey. The active tab is Soft White at 500 with a 5px teal square.
+- **Sidebar:** Secondary Grey links with a 6px radius. Hover uses Panel Graphite. The active link uses Raised Graphite with a 5px teal square in the gutter, so the label does not shift. The active table of contents entry turns teal with no square.
+- **Mobile:** Material's drawer with full-width rows, each divided by a 1px border.
+
+### Code panels
+Panel Graphite, 8px radius, with a 1px border. A file name or tab row sits in a Raised Graphite title bar, with a 1px teal indicator under the active tab. A copy icon sits at the top right. Inline code is a small 4px outlined chip on Panel Graphite.
+
+### Package field
+The home hero's right column: an 8px grid of tiny squares on Panel Graphite, drawn on a canvas, with the package name, position squares and a pause button in a footer row. It morphs to one recognisable scene per package every 6 seconds, in step with the heading carousel: a robot broadcasting to clients for Agents, a terminal inside marching walls for Sandboxes, shipping containers on a crane for Containers, a cloud serving requests for Workers, and the wind symbol blowing blocks off a stack for Wynd. Squares near the pointer brighten. The package preview below follows it, and picking a package in the preview moves the hero and stops the carousel. It holds on hover or focus of the hero or the preview and stops off screen. Reduced motion starts it stopped on a still frame. It stays flat, so it never reads as the isometric package diagram.
+
+### Callouts
+A panel with a 6px square and mono label in a 72px left column, text in the right column, stacked on phones. Each type tints its label, marker, border (38%) and background (7%): teal for notes, tips and other information, amber for warnings, cautions and quote callouts with a bold label, red for danger, errors and failures.
+
+### Command
+A bordered inline group holding a purple Geist Mono command, a Decoration Grey prompt the reader cannot select, and an icon button that copies the command.
+
+### Package palette
+The signature component. A 10px panel with a filter field, rows and a keycap hint row on the left, and the selected package's summary and code on the right. Each row holds a square, a name, a mono package id and a badge. The selected row uses Raised Graphite and a teal square. Arrow keys swap the preview, and Enter opens the docs. The pane enters over 160ms with a 2px rise. Without JavaScript, the panes stay stacked and readable.
+
+### Fact table
+A bordered definition list with 1px row rules, 12px text, Label Grey terms and Soft White values. Status rows carry a square marker.
+
+### Status bar
+The footer's last row, in 11px Secondary Grey on Graphite Ground, with an amber square and the alpha state in Geist Mono on the left and links on the right. It holds the independence statement that PRODUCT.md requires.
+
+### Ecosystem diagram
+An SVG isometric scene in a 10px panel, with Geist Mono labels, 1px hairline strokes and teal for the active path. Its faces use the graphite steps, plus three in-between greys scoped to the diagram (`#1e2022`, `#26292c`, `#1c1e20`). Uppercase tracked labels belong to this SVG only.
+
+## Do's and Don'ts
+
+### Do:
+- **Do** keep the page dark, using only the three graphite steps for grounds.
+- **Do** use 1px Hairline borders (#34373b) and thin rules to separate things.
+- **Do** set commands, shortcuts, statuses, package names and file names in Geist Mono.
+- **Do** mark the current item with a 5px or 6px teal square.
+- **Do** show a keycap only when the shortcut works.
+- **Do** write rem values against the 20px root, where .05rem is 1px.
+- **Do** use Secondary Grey (#92979e) for small text on Panel Graphite or Raised Graphite.
+- **Do** map new colours through the `--cw-*` tokens and Material's `--md-*` variables, so generated API pages inherit them.
+
+### Don't:
+- **Don't** add a light theme or a theme toggle.
+- **Don't** build a hero with a mascot or a grid of feature cards. The puffin stays in the header as the logo.
+- **Don't** use Decoration Grey (#686d74) for text a reader needs.
+- **Don't** put Label Grey (#7f858c) on Panel Graphite or Raised Graphite.
+- **Don't** use purple for links, buttons or general emphasis.
+- **Don't** raise amber's saturation, or use it for anything other than warnings, alpha status and syntax values.
+- **Don't** divide page sections with background bands.
+- **Don't** put a shadow on a panel in the document flow, other than the palette's contact shadow.
+- **Don't** set uppercase or tracked labels in HTML chrome.
+- **Don't** use radii above 10px, or pill shapes.
diff --git a/PRODUCT.md b/PRODUCT.md
new file mode 100644
index 0000000..6228f5f
--- /dev/null
+++ b/PRODUCT.md
@@ -0,0 +1,43 @@
+# Product
+
+
+
+## Platform
+
+web
+
+## Users
+
+Python developers evaluating Crosswind because they want Cloudflare's TypeScript-only developer kits in Python. They need to see the packages and real code, pick a package, and start. People already using Crosswind are the second audience, and they use the docs as reference.
+
+## Product Purpose
+
+Crosswind is an unofficial set of typed, async Python SDKs and tools for Cloudflare Python Workers. Each package ports one TypeScript kit or official tool, so developers subclass Python classes and never write Pyodide or FFI calls.
+
+## Positioning
+
+Each SDK keeps the wire protocol of its official counterpart, so TypeScript clients such as the `useAgent` React hook connect to a Python Worker unchanged.
+
+## Capabilities and Constraints
+
+- Packages: `cf-agents`, `containers-py`, `crosswind-sandboxes`, `crosswind-workers` and the `wynd` CLI.
+- The docs site is MkDocs Material, deployed on Cloudflare Pages, with API pages generated by mkdocstrings.
+- Every package is alpha and pre-1.0. The docs must keep telling readers to pin exact versions.
+- Python Workers run on Pyodide, so not every PyPI package imports.
+
+## Brand Commitments
+
+- The name is Crosswind and the puffin logo stays.
+- Crosswind is independent and not affiliated with or endorsed by Cloudflare. The docs must say so.
+- The user pinned the visual direction: dark, minimal, native tooling. See `DESIGN.md`.
+
+## Evidence on Hand
+
+- Mosslight Valley, a demo game whose server uses `cf-agents`.
+- No customers, benchmarks or testimonials exist. Do not invent them.
+
+## Product Principles
+
+- Show code before claims.
+- Keep Python types at every public boundary.
+- State what is alpha or missing.
diff --git a/docs/assets/hero-img.png b/docs/assets/hero-img.png
deleted file mode 100644
index 4530f3d..0000000
Binary files a/docs/assets/hero-img.png and /dev/null differ
diff --git a/docs/docs/assets/hero-img.png b/docs/docs/assets/hero-img.png
deleted file mode 100644
index 18afba9..0000000
Binary files a/docs/docs/assets/hero-img.png and /dev/null differ
diff --git a/docs/docs/containers/outbound-traffic.md b/docs/docs/containers/outbound-traffic.md
index 4936580..1f2ad0d 100644
--- a/docs/docs/containers/outbound-traffic.md
+++ b/docs/docs/containers/outbound-traffic.md
@@ -60,12 +60,11 @@ characters, so `*.example.com`, `api.*.com` and `goo*gle` are all valid.
container needs both. The SDK ignores a trailing dot on the hostname. Blocked
requests get a `520` response with the body `Origin is disallowed`.
-> **Note**
->
-> Host lists apply to HTTP traffic, and to HTTPS once
-> [HTTPS interception](#https) is on. See the
-> [platform docs](https://developers.cloudflare.com/containers/configuration/outbound-traffic/)
-> for how the platform handles other ports and protocols.
+!!! note
+ Host lists apply to HTTP traffic, and to HTTPS once
+ [HTTPS interception](#https) is on. See the
+ [platform docs](https://developers.cloudflare.com/containers/configuration/outbound-traffic/)
+ for how the platform handles other ports and protocols.
## Outbound handlers
@@ -332,10 +331,9 @@ rule that applies decides what happens:
`allowed_hosts` or `enable_internet` is `True`. Otherwise the SDK blocks
it.
-> **Note**
->
-> If your only rules are class-level `outbound_by_host` entries, only requests
-> to those hosts go through `ContainerProxy`. Anything else, such as a
-> catch-all, a host list or any runtime change, routes all of the
-> container's HTTP traffic through it. That stays in place until the container
-> restarts.
+!!! note
+ If your only rules are class-level `outbound_by_host` entries, only requests
+ to those hosts go through `ContainerProxy`. Anything else, such as a
+ catch-all, a host list or any runtime change, routes all of the
+ container's HTTP traffic through it. That stays in place until the container
+ restarts.
diff --git a/docs/docs/index.md b/docs/docs/index.md
index f574b7e..ac9090f 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -6,103 +6,171 @@ hide:
- toc
---
-=== "Agents"
+
- ```python
- from workers import Request, Response, WorkerEntrypoint
- from agents import Agent, callable, route_agent_request
+
+
+
+**Agents** `cf-agents`
+Stateful agents with WebSocket clients, schedules, durable tasks and streaming chat.
+
+
+[Overview](agents/overview.md){ .md-button } [Build an agent](agents/getting-started.md){ .md-button }
+
+
+
+```python
+from workers import Request, Response, WorkerEntrypoint
+from agents import Agent, callable, route_agent_request
+
+
+class Counter(Agent):
+ initial_state = {"count": 0}
+
+ @callable # clients call this over a WebSocket
+ async def increment(self, by: int = 1) -> int:
+ self.set_state({"count": self.state["count"] + by}) # saved, sent to every client
+ return self.state["count"]
+
+
+class Default(WorkerEntrypoint):
+ async def fetch(self, request: Request) -> Response:
+ # /agents/counter/ reaches the counter called
+ return await route_agent_request(request, self.env) or Response("Not found", status=404)
+```
+
+
+
+
+
+
+**Sandboxes** `crosswind-sandboxes`
+
+Read and write files, mount S3 buckets and back up directories in a sandbox container.
+
+
+[Overview](sandboxes/overview.md){ .md-button } [Create a sandbox](sandboxes/getting-started.md){ .md-button }
+
+
+
+```python
+from sandboxes import Files
+from workers import DurableObject, Request, Response, WorkerEntrypoint
+
+
+class Sandbox(DurableObject):
+ async def save(self, text: str) -> str:
+ if not self.ctx.container.running:
+ self.ctx.container.start()
+
+ files = Files(self.ctx.container)
+ await files.mkdir("/workspace", recursive=True)
+ await files.write_file("/workspace/notes.txt", text) # still there on the next request
+ entries = await files.read_directory("/workspace")
+ return ", ".join(entry.name for entry in entries)
- class Counter(Agent):
- initial_state = {"count": 0}
- @callable # clients call this over a WebSocket
- async def increment(self, by: int = 1) -> int:
- self.set_state({"count": self.state["count"] + by}) # saved, sent to every client
- return self.state["count"]
+class Default(WorkerEntrypoint):
+ async def fetch(self, request: Request) -> Response:
+ # One sandbox per user, with its own container and files
+ user_id = request.url.rsplit("/", 1)[-1]
+ sandbox = self.env.SANDBOX.getByName(user_id)
+ return Response(await sandbox.save(await request.text()))
+```
+
- class Default(WorkerEntrypoint):
- async def fetch(self, request: Request) -> Response:
- # /agents/counter/ reaches the counter called
- return await route_agent_request(request, self.env) or Response("Not found", status=404)
- ```
+
+
+
+**Containers** `containers-py`
-=== "Containers"
+Start, stop and route requests to Cloudflare Containers, and filter their outbound traffic.
+
+
+[Overview](containers/overview.md){ .md-button } [Run a container](containers/getting-started.md){ .md-button }
+
+
+
+```python
+from workers import Request, Response, WorkerEntrypoint
+from containers import Container, get_container
- ```python
- from workers import Request, Response, WorkerEntrypoint
- from containers import Container, get_container
+class Transcoder(Container):
+ default_port = 8080
+ sleep_after = "5m"
+ enable_internet = False
- class Transcoder(Container):
- default_port = 8080
- sleep_after = "5m"
- enable_internet = False
+class Default(WorkerEntrypoint):
+ async def fetch(self, request: Request) -> Response:
+ # One container per video, started on the first request
+ video_id = request.url.rsplit("/", 1)[-1]
+ container = get_container(self.env.TRANSCODER, video_id)
+ return await container.fetch(request)
+```
- class Default(WorkerEntrypoint):
- async def fetch(self, request: Request) -> Response:
- # One container per video, started on the first request
- video_id = request.url.rsplit("/", 1)[-1]
- container = get_container(self.env.TRANSCODER, video_id)
- return await container.fetch(request)
- ```
+
-=== "Sandboxes"
+
+
+
+**Workers** `crosswind-workers`
- ```python
- from sandboxes import Files
- from workers import DurableObject, Request, Response, WorkerEntrypoint
+Drop-in replacement for the official `workers` package, with type hints on bindings, requests and Durable Objects.
+
+
+[Overview](workers/overview.md){ .md-button } [Write a Worker](workers/getting-started.md){ .md-button }
+
+
+```python
+from env import Env # generated by wynd from wrangler.jsonc
+from workers import DurableObject, Request, Response, WorkerEntrypoint
- class Sandbox(DurableObject):
- async def save(self, text: str) -> str:
- if not self.ctx.container.running:
- self.ctx.container.start()
- files = Files(self.ctx.container)
- await files.mkdir("/workspace", recursive=True)
- await files.write_file("/workspace/notes.txt", text) # still there on the next request
- entries = await files.read_directory("/workspace")
- return ", ".join(entry.name for entry in entries)
+class Counter(DurableObject[Env]):
+ async def increment(self, by: int) -> int:
+ count = (await self.ctx.storage.get("count") or 0) + by
+ await self.ctx.storage.put("count", count)
+ return count
- class Default(WorkerEntrypoint):
- async def fetch(self, request: Request) -> Response:
- # One sandbox per user, with its own container and files
- user_id = request.url.rsplit("/", 1)[-1]
- sandbox = self.env.SANDBOX.getByName(user_id)
- return Response(await sandbox.save(await request.text()))
- ```
+class Default(WorkerEntrypoint[Env]):
+ async def fetch(self, request: Request) -> Response:
+ # self.env.COUNTER is typed, so a misspelled method fails the type check
+ count = await self.env.COUNTER.get_by_name("global").increment(1)
+ return Response.json({"count": count})
+```
-=== "Workers"
+
- ```python
- from env import Env # generated by wynd from wrangler.jsonc
- from workers import DurableObject, Request, Response, WorkerEntrypoint
+
+
+
+**Wynd** `wynd`
+Replaces pywrangler. It drops vendored files your Worker never imports before each upload.
+
+
+[Overview](wynd/overview.md){ .md-button } [Switch from pywrangler](wynd/getting-started.md){ .md-button }
+
+
- class Counter(DurableObject[Env]):
- async def increment(self, by: int) -> int:
- count = (await self.ctx.storage.get("count") or 0) + by
- await self.ctx.storage.put("count", count)
- return count
+```sh
+uvx wynd init # write a new crosswind-workers project
+uvx wynd dev # install packages for the Worker's Python, then wrangler dev
+uvx wynd deploy # prune unused packages, then wrangler deploy
+uvx wynd tail # anything else goes to Wrangler unchanged
+```
+
- class Default(WorkerEntrypoint[Env]):
- async def fetch(self, request: Request) -> Response:
- # self.env.COUNTER is typed, so a misspelled method fails the type check
- count = await self.env.COUNTER.get_by_name("global").increment(1)
- return Response.json({"count": count})
- ```
+
-> **Warning**
->
-> Every Crosswind package is in alpha. A minor release can rename or remove
-> an API, so an unpinned dependency can break a deploy that worked yesterday.
-> Pin exact versions, test each upgrade before you deploy it, and expect to
-> change your code when you upgrade. See [Status](#status).
+
## What Crosswind is
@@ -115,18 +183,26 @@ Each Crosswind package ports one of those kits to Python. You subclass a Python
class, override `async` methods and call typed functions, and the package
makes the JavaScript calls.
+
+
+
+
## Packages
| Project | Package | What it does | Start here | Version |
| ------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------- |
-| [Agents](agents/overview.md) | `cf-agents` | Stateful agents with WebSocket clients, schedules, durable tasks and streaming chat. | [Build an agent](agents/getting-started.md) |  |
-| [Containers](containers/overview.md) | `containers-py` | Start, stop and route requests to Cloudflare Containers, and filter their outbound traffic. | [Run a container](containers/getting-started.md) |  |
-| [Sandboxes](sandboxes/overview.md) | `crosswind-sandboxes` | Read and write files, mount S3 buckets and back up directories in a sandbox container. | [Create a sandbox](sandboxes/getting-started.md) |  |
-| [Workers](workers/overview.md) | `crosswind-workers` | Drop-in replacement for the official `workers` package, with type hints on bindings, requests and Durable Objects. | [Write a Worker](workers/getting-started.md) |  |
-| [Wynd](wynd/overview.md) | `wynd` | Replaces pywrangler. It drops vendored files your Worker never imports before each upload. | [Switch from pywrangler](wynd/getting-started.md) |  |
+| [Agents](agents/overview.md) | `cf-agents` | Stateful agents with WebSocket clients, schedules, durable tasks and streaming chat. | [Build an agent](agents/getting-started.md) |  |
+| [Containers](containers/overview.md) | `containers-py` | Start, stop and route requests to Cloudflare Containers, and filter their outbound traffic. | [Run a container](containers/getting-started.md) |  |
+| [Sandboxes](sandboxes/overview.md) | `crosswind-sandboxes` | Read and write files, mount S3 buckets and back up directories in a sandbox container. | [Create a sandbox](sandboxes/getting-started.md) |  |
+| [Workers](workers/overview.md) | `crosswind-workers` | Drop-in replacement for the official `workers` package, with type hints on bindings, requests and Durable Objects. | [Write a Worker](workers/getting-started.md) |  |
+| [Wynd](wynd/overview.md) | `wynd` | Replaces pywrangler. It drops vendored files your Worker never imports before each upload. | [Switch from pywrangler](wynd/getting-started.md) |  |
For a new Python Worker, use `crosswind-workers` and deploy it with Wynd.
+
+
+
+
## How the packages work
- **Python classes.** You subclass a class and override `async` methods.
@@ -140,31 +216,65 @@ For a new Python Worker, use `crosswind-workers` and deploy it with Wynd.
Starlette, and WSGI apps such as Flask. See
[Serve FastAPI or Flask](workers/web-frameworks.md).
+
+
+ How Agents, Containers, Workers and Wynd connect
+
+ Python sits at the centre of Crosswind. Agents, Containers, Wynd and Workers connect to it. Wynd drops the dependencies a Worker never imports, packs the rest into a bundle and deploys it to Workers. Select a package in the diagram to open its docs.
+
+
+
Python deserves the full power of the edge.
+
One core, many packages.
+
Each package does one job.
+
More of the edge. In Python.
+
+
+
+
+
+
+
+
+
+
+
+
Select to open the docs
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
## Demo
-
-
Mosslight Valley is a small game that runs on Python Workers. Its server is
written with `cf-agents`.
[Open it in a new tab](https://agents-py-mosslight-valley.reachvishm8605.workers.dev/){ target="_blank" }
+
+
+
+
## Status
-Every package is alpha and pre-1.0. A minor release can break your code, so
-pin exact versions:
+Every package is alpha and pre-1.0. A minor release can rename or remove an
+API, so an unpinned dependency can break a deploy that worked yesterday. Pin
+exact versions, test each upgrade before you deploy it, and expect to change
+your code when you upgrade:
```sh
uv add "crosswind-workers=="
@@ -173,3 +283,5 @@ uv add "crosswind-workers=="
Each SDK's overview lists the features it doesn't port yet. Crosswind is an
independent community project. It isn't affiliated with or endorsed by
Cloudflare.
+
+
diff --git a/docs/docs/javascripts/field.js b/docs/docs/javascripts/field.js
new file mode 100644
index 0000000..5941fcd
--- /dev/null
+++ b/docs/docs/javascripts/field.js
@@ -0,0 +1,452 @@
+// Home hero: a grid of tiny squares that morphs into one scene per package, in
+// step with the heading carousel. Each scene is a small picture of what the package does.
+(() => {
+ const rotator = document.querySelector(".cw-rotator");
+ const panel = document.querySelector(".cw-field");
+ if (!rotator || !panel) return;
+
+ const reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
+ const EVERY = 6000;
+ const MORPH = 0.9; // seconds
+ const CELL = 8; // CSS pixels between squares
+ const words = [...rotator.children];
+
+ panel.innerHTML = `
+
+
+
+
+
+
+
+
`;
+ const canvas = panel.querySelector("canvas");
+ const ctx = canvas.getContext("2d");
+ const pkg = panel.querySelector(".cw-field__pkg");
+ const dots = panel.querySelector(".cw-field__dots");
+ const pause = panel.querySelector(".cw-field__pause");
+
+ // Colour ramps from the site tokens, so a palette change reaches the canvas
+ const token = (name) => {
+ const hex = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+ return [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+ };
+ const ramp = (to) => {
+ const from = token("--cw-border");
+ return Array.from({ length: 33 }, (_, i) =>
+ `rgb(${from.map((c, k) => Math.round(c + (to[k] - c) * (i / 32) ** 0.8)).join()})`);
+ };
+ const TEAL = ramp(token("--cw-accent"));
+ const PURPLE = ramp(token("--cw-purple"));
+
+ const clamp = (n) => Math.min(1, Math.max(0, n));
+ const smooth = (a, b, n) => {
+ const p = clamp((n - a) / (b - a));
+ return p * p * (3 - 2 * p);
+ };
+ const hash = (a, b = 0) => {
+ const s = Math.sin(a * 127.1 + b * 311.7) * 43758.5453;
+ return s - Math.floor(s);
+ };
+
+ // Scenes draw into the current buffer through these helpers
+ let cols = 0;
+ let rows = 0;
+ let values = new Float32Array(0);
+ let tones = new Uint8Array(0);
+ const put = (x, y, value, purple = false) => {
+ const cx = Math.round(x);
+ const cy = Math.round(y);
+ if (cx < 0 || cy < 0 || cx >= cols || cy >= rows) return;
+ const i = cy * cols + cx;
+ if (value < values[i]) return;
+ values[i] = value;
+ tones[i] = purple ? 1 : 0;
+ };
+ const fill = (x, y, w, h, value, purple) => {
+ for (let j = 0; j < h; j++) for (let i = 0; i < w; i++) put(x + i, y + j, value, purple);
+ };
+ const outline = (x, y, w, h, value, purple) => {
+ fill(x, y, w, 1, value, purple);
+ fill(x, y + h - 1, w, 1, value, purple);
+ fill(x, y, 1, h, value, purple);
+ fill(x + w - 1, y, 1, h, value, purple);
+ };
+ const sprite = (lines, x, y, shade) => lines.forEach((line, j) => {
+ for (let i = 0; i < line.length; i++) if (line[i] === "#") put(x + i, y + j, shade(x + i, y + j));
+ });
+
+ const CLOUD = [
+ "..........#####..........",
+ ".......###.....##........",
+ "......#..........#.......",
+ "....###...........###....",
+ "...#.................##..",
+ "..#....................#.",
+ ".#......................#",
+ ".#......................#",
+ "..#....................#.",
+ "...####################..",
+ ];
+ const BOLT = ["....##", "...##.", "..##..", ".#####", "...##.", "..##..", ".##..."];
+ const WIND = [
+ "...........####...........",
+ "..........#....#..........",
+ "...............#..........",
+ "...............#....####..",
+ "###############....#....#.",
+ "........................#.",
+ "########################..",
+ "..........................",
+ "################..........",
+ "................#.........",
+ "................#.........",
+ "..........#....#..........",
+ "...........####...........",
+ ];
+
+ const SCENES = {
+ // A robot that broadcasts its state to the clients on either side
+ Agents(t) {
+ const cx = Math.floor(cols / 2);
+ const cy = Math.floor(rows / 2) + 2;
+ const mid = Math.floor(rows / 2);
+ const blink = t % 3.4 < 0.14;
+ fill(cx - 7, cy - 5, 15, 11, 0.2);
+ outline(cx - 7, cy - 5, 15, 11, 0.9);
+ fill(cx - 8, cy - 2, 1, 4, 0.7);
+ fill(cx + 8, cy - 2, 1, 4, 0.7);
+ fill(cx, cy - 8, 1, 3, 0.7);
+ fill(cx - 1, cy - 10, 3, 2, 0.5 + 0.5 * Math.max(0, Math.sin(t * 3.2)), true);
+ fill(cx - 4, blink ? cy - 1 : cy - 2, 3, blink ? 1 : 2, 1);
+ fill(cx + 2, blink ? cy - 1 : cy - 2, 3, blink ? 1 : 2, 1);
+ fill(cx - 2, cy + 3, 5, 1, 0.7);
+ const reach = Math.min(23, cols / 2 - 4);
+ const r = 10 + ((t * 9) % (reach + 4));
+ for (const side of [-1, 1]) {
+ for (let j = -9; j <= 9; j++) {
+ const dx = Math.sqrt(Math.max(0, r * r - j * j));
+ if (dx > 9.5) put(cx + side * dx, mid + j, 0.55 * (1 - (r - 10) / (reach + 4)) + 0.2);
+ }
+ for (const off of [-7, 0, 7]) {
+ const x = cx + side * reach;
+ const hit = Math.max(0, 1 - Math.abs(r - Math.hypot(reach, off)) / 2.5);
+ fill(x - 2, mid + off - 2, 5, 4, 0.15 + hit * 0.45, true);
+ outline(x - 2, mid + off - 2, 5, 4, 0.5 + hit * 0.5, true);
+ }
+ }
+ },
+
+ // Code running in a terminal, inside walls that nothing crosses
+ Sandboxes(t) {
+ const half = Math.min(25, Math.floor(cols / 2) - 2);
+ const cx = Math.floor(cols / 2);
+ const [left, right, top, bottom] = [cx - half, cx + half, 1, rows - 2];
+ const march = Math.floor(t * 5);
+ const dash = (n) => ((n + march) % 3 === 0 ? 0.2 : 0.8);
+ for (let x = left; x <= right; x++) {
+ put(x, top, dash(x), true);
+ put(x, bottom, dash(right - x), true);
+ }
+ for (let y = top; y <= bottom; y++) {
+ put(left, y, dash(y), true);
+ put(right, y, dash(bottom - y), true);
+ }
+ const termW = 27;
+ const termH = 13;
+ const tx = cx - 13;
+ const ty = Math.floor((rows - termH) / 2);
+ fill(tx, ty, termW, termH, 0.14);
+ outline(tx, ty, termW, termH, 0.85);
+ fill(tx + 1, ty + 1, termW - 2, 1, 0.4);
+ fill(tx + 2, ty + 1, 2, 1, 0.8);
+ const lens = [14, 9, 18, 6];
+ const typed = (t * 11) % 62;
+ let used = 0;
+ lens.forEach((len, line) => {
+ const y = ty + 3 + line * 2;
+ put(tx + 2, y, 0.6, true);
+ const shown = Math.min(len, Math.max(0, typed - used));
+ fill(tx + 4, y, shown, 1, 1);
+ if (shown > 0 && shown < len && t % 0.5 < 0.3) put(tx + 4 + shown, y, 1, true);
+ used += len;
+ });
+ // One grain bouncing around the terminal, turned back at the wall
+ const span = (n) => (a, b) => {
+ const p = (t * n) % (2 * (b - a));
+ return a + (p < b - a ? p : 2 * (b - a) - p);
+ };
+ if (half > 18) {
+ put(span(9)(left + 2, tx - 2), span(6)(top + 2, bottom - 2), 1);
+ put(span(8)(tx + termW + 1, right - 2), span(7)(top + 2, bottom - 2), 1);
+ }
+ },
+
+ // Shipping containers: a crane lowers one onto the stack and lifts it off again
+ Containers(t) {
+ const W = 13;
+ const H = 5;
+ const box = (x, y, value, led, purple) => {
+ fill(x, y, W, H, value * 0.22, purple);
+ outline(x, y, W, H, value, purple);
+ for (let i = 2; i < W - 3; i += 2) fill(x + i, y + 1, 1, H - 2, value * 0.5, purple);
+ fill(x + W - 3, y + 1, 1, H - 2, value * 0.8, purple);
+ put(x + W - 2, y + 2, led);
+ };
+ const cx = Math.floor(cols / 2);
+ const bottom = rows - 1 - H;
+ const x0 = cx - Math.floor((W * 3 + 2) / 2);
+ for (let i = 0; i < 3; i++) box(x0 + i * (W + 1), bottom, 0.7, hash(i, Math.floor(t * 0.7)) > 0.4 ? 1 : 0.2);
+ for (let i = 0; i < 2; i++) box(x0 + i * (W + 1), bottom - H - 1, 0.7, hash(i + 5, Math.floor(t * 0.9)) > 0.4 ? 1 : 0.2, i === 1);
+ const slot = x0 + 2 * (W + 1);
+ const rest = bottom - H - 1;
+ const c = t % 7;
+ const lift = smooth(0, 2.2, c) * (1 - smooth(4.6, 6.8, c));
+ const y = 3 + (rest - 3) * lift;
+ fill(0, 0, cols, 1, 0.3);
+ const hookX = slot + Math.floor(W / 2);
+ fill(hookX, 1, 1, Math.max(0, Math.round(y) - 1), 0.55);
+ box(slot, y, 1, lift > 0.98 ? 1 : 0.2);
+ },
+
+ // Requests fly into the Cloudflare cloud, and responses leave the other side
+ Workers(t) {
+ const x = Math.floor((cols - CLOUD[0].length) / 2);
+ const y = Math.floor((rows - CLOUD.length) / 2);
+ const beat = Math.max(0, Math.sin(t * 5)) ** 4;
+ CLOUD.forEach((line, j) => fill(x + line.indexOf("#"), y + j, line.lastIndexOf("#") - line.indexOf("#") + 1, 1, 0.16));
+ sprite(CLOUD, x, y, () => 0.95);
+ sprite(BOLT, x + 9, y + 2, () => 0.7 + beat * 0.3);
+ [3, 6, 9].forEach((lane, i) => {
+ const inEnd = x + 2;
+ const outStart = x + CLOUD[0].length - 2;
+ for (let k = 0; k < 2; k++) {
+ const p = (t * 0.55 + i * 0.31 + k * 0.5) % 1;
+ fill(p * inEnd - 1, y + lane - 1, 2, 2, 0.5 + 0.5 * smooth(0, 0.3, p));
+ fill(outStart + p * (cols - outStart), y + lane - 1, 2, 2, 1 - 0.5 * smooth(0.7, 1, p), true);
+ }
+ });
+ },
+
+ // Wind blowing the packages nothing imports off the stack
+ Wynd(t) {
+ const total = WIND[0].length + 16;
+ const x = Math.max(1, Math.floor((cols - total) / 2));
+ const y = Math.floor((rows - WIND.length) / 2);
+ const head = (t * 22) % 46 - 6;
+ sprite(WIND, x, y, (px) => 0.72 + 0.28 * Math.max(0, 1 - Math.abs(px - x - head) / 7));
+ const sx = x + WIND[0].length + 2;
+ const cycle = t % 5;
+ for (let row = 0; row < 4; row++) {
+ for (let col = 0; col < 2; col++) {
+ const bx = sx + col * 5;
+ const by = y + 1 + row * 3;
+ const unused = hash(row, col + 1) > 0.5;
+ if (!unused) {
+ fill(bx, by, 4, 2, 0.9);
+ continue;
+ }
+ const gone = smooth(0.8 + row * 0.15, 3 + row * 0.15, cycle) * (1 - smooth(4.6, 5, cycle));
+ const fade = 1 - smooth(0.3, 1, gone);
+ fill(bx + gone * 18, by - Math.sin(gone * 3) * 2, 4, 2, 0.8 * fade, true);
+ }
+ }
+ },
+ };
+ const NAMES = {
+ Agents: "cf-agents",
+ Sandboxes: "crosswind-sandboxes",
+ Containers: "containers-py",
+ Workers: "crosswind-workers",
+ Wynd: "wynd",
+ };
+ const order = words.slice(0, -1).map((w) => w.textContent);
+
+ let scale = 1;
+ let current = 0;
+ let previous = 0;
+ let morphStart = -9;
+ let clock = reduced ? 8 : 0;
+ let stopped = reduced;
+ let held = 0;
+ let pointer = null;
+
+ function render(name) {
+ values = new Float32Array(cols * rows);
+ tones = new Uint8Array(cols * rows);
+ SCENES[name](clock);
+ return [values, tones];
+ }
+
+ function draw() {
+ const m = reduced ? 1 : smooth(0, MORPH, clock - morphStart);
+ const [to, toTones] = render(order[current]);
+ const [from, fromTones] = m < 1 ? render(order[previous]) : [to, toTones];
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
+ for (let y = 0; y < rows; y++) {
+ for (let x = 0; x < cols; x++) {
+ const i = y * cols + x;
+ // Sweep the change across the grid so it reads as one motion
+ const local = m < 1 ? smooth(0, 1, m * 1.6 - (x / cols) * 0.6) : 1;
+ let value = from[i] + (to[i] - from[i]) * local;
+ const purple = local < 0.5 ? fromTones[i] : toTones[i];
+ if (pointer) value += Math.max(0, 1 - Math.hypot(x - pointer.x, y - pointer.y) / 5) * 0.6;
+ value = clamp(value);
+ const size = Math.round((1.2 + value * 4.6) * scale);
+ ctx.fillStyle = (purple ? PURPLE : TEAL)[Math.round(value * 32)];
+ ctx.fillRect(
+ Math.round((x * CELL + CELL / 2) * scale - size / 2),
+ Math.round((y * CELL + CELL / 2) * scale - size / 2),
+ size,
+ size,
+ );
+ }
+ }
+ }
+
+ function resize() {
+ const box = canvas.parentElement.getBoundingClientRect();
+ scale = devicePixelRatio || 1;
+ canvas.width = Math.round(box.width * scale);
+ canvas.height = Math.round(box.height * scale);
+ cols = Math.floor(box.width / CELL);
+ rows = Math.floor(box.height / CELL);
+ ctx.setTransform(1, 0, 0, 1, (canvas.width - cols * CELL * scale) / 2, (canvas.height - rows * CELL * scale) / 2);
+ draw();
+ }
+
+ // Runs only while the panel is on screen and the carousel isn't paused
+ let visible = true;
+ let raf = 0;
+ let last = 0;
+ function frame(now) {
+ clock += Math.min(0.05, (now - last) / 1000);
+ last = now;
+ draw();
+ raf = requestAnimationFrame(frame);
+ }
+ function sync() {
+ const run = visible && !stopped && !document.hidden;
+ if (run && !raf) {
+ last = performance.now();
+ raf = requestAnimationFrame(frame);
+ } else if (!run && raf) {
+ cancelAnimationFrame(raf);
+ raf = 0;
+ }
+ }
+
+ // The word list ends with a copy of the first word, so the loop always moves upward
+ const moveWords = (index) => words.forEach((w) => (w.style.transform = `translateY(${-index * 100}%)`));
+ words[0].addEventListener("transitionend", () => {
+ if (!words[0].style.transform.includes(`-${order.length * 100}%`)) return;
+ words.forEach((w) => (w.style.transition = "none"));
+ moveWords(0);
+ void rotator.offsetHeight; // commit the jump before transitions come back
+ words.forEach((w) => (w.style.transition = ""));
+ });
+
+ const buttons = order.map((name, i) => {
+ const b = document.createElement("button");
+ b.type = "button";
+ b.className = "cw-field__dot";
+ b.setAttribute("aria-label", `Show ${name}`);
+ b.title = name;
+ b.addEventListener("click", () => {
+ stopped = true;
+ renderPause();
+ show(i);
+ sync();
+ });
+ dots.append(b);
+ return b;
+ });
+
+ function show(index, wrap) {
+ previous = current;
+ current = index;
+ morphStart = clock;
+ moveWords(wrap ? order.length : index);
+ pkg.textContent = NAMES[order[index]];
+ document.dispatchEvent(new CustomEvent("cw:package", { detail: order[index] }));
+ buttons.forEach((b, i) => b.setAttribute("aria-pressed", i === index));
+ // A paused canvas still has to finish the change, so play out the morph
+ if (stopped && !reduced) {
+ const until = performance.now() + MORPH * 1000;
+ let at = performance.now();
+ const finish = (now) => {
+ clock += (now - at) / 1000;
+ at = now;
+ draw();
+ if (now < until && stopped) requestAnimationFrame(finish);
+ };
+ requestAnimationFrame(finish);
+ } else {
+ draw();
+ }
+ }
+
+ function renderPause() {
+ pause.setAttribute("aria-label", stopped ? "Play the animation" : "Pause the animation");
+ pause.title = stopped ? "Play" : "Pause";
+ pause.innerHTML = stopped
+ ? ''
+ : '';
+ }
+
+ pause.addEventListener("click", () => {
+ stopped = !stopped;
+ renderPause();
+ sync();
+ });
+
+ canvas.parentElement.addEventListener("pointermove", (event) => {
+ if (reduced) return;
+ const box = canvas.getBoundingClientRect();
+ pointer = { x: (event.clientX - box.left) / CELL - 0.5, y: (event.clientY - box.top) / CELL - 0.5 };
+ if (!raf) draw();
+ });
+ canvas.parentElement.addEventListener("pointerleave", () => {
+ pointer = null;
+ if (!raf) draw();
+ });
+
+ // Hold on one package while the reader points at or tabs through the hero's moving parts
+ const preview = document.querySelector(".cw-palette");
+ for (const target of [panel, preview, rotator.parentElement]) {
+ target?.addEventListener("pointerenter", () => (held += 1));
+ target?.addEventListener("pointerleave", () => (held = Math.max(0, held - 1)));
+ }
+ for (const target of [panel, preview]) {
+ target?.addEventListener("focusin", () => (held += 1));
+ target?.addEventListener("focusout", () => (held = Math.max(0, held - 1)));
+ }
+
+ // Picking a package in the preview moves the hero too, and stops the carousel there
+ document.addEventListener("cw:pick", (event) => {
+ stopped = true;
+ renderPause();
+ show(order.indexOf(event.detail));
+ sync();
+ });
+
+ setInterval(() => {
+ if (stopped || held || document.hidden || !visible) return;
+ const next = (current + 1) % order.length;
+ show(next, next === 0);
+ }, EVERY);
+
+ new IntersectionObserver(([entry]) => {
+ visible = entry.isIntersecting;
+ sync();
+ }).observe(panel);
+ document.addEventListener("visibilitychange", sync);
+ new ResizeObserver(resize).observe(canvas.parentElement);
+
+ panel.hidden = false;
+ pause.hidden = reduced;
+ renderPause();
+ resize();
+ show(0);
+ sync();
+})();
diff --git a/docs/docs/javascripts/home.js b/docs/docs/javascripts/home.js
new file mode 100644
index 0000000..7b0995a
--- /dev/null
+++ b/docs/docs/javascripts/home.js
@@ -0,0 +1,132 @@
+// Home page package palette. Without this script the panes stay stacked and readable.
+// Rows are vertical tabs: arrows move and preview, Enter opens the package docs.
+(() => {
+ const palette = document.querySelector(".cw-palette");
+ if (!palette) return;
+
+ const panes = [...palette.querySelectorAll(".cw-pane")];
+ const side = document.createElement("div");
+ side.className = "cw-palette__side";
+ side.innerHTML = `
+
+
+
+
Crosswind
{#- The last word repeats the first so the loop restarts without a jump #}
- AgentsContainersWorkersWyndAgents
+ AgentsSandboxesContainersWorkersWyndAgents
-
Crosswind is a set of typed, async Python packages and tools for Python Workers. It ports the Agents and Containers SDKs, replaces the workers package with typed APIs, and replaces pywrangler with wynd.
+
Crosswind is a set of typed, async Python packages and tools for Python Workers. It ports the Agents, Containers and Sandboxes SDKs, replaces the workers package with typed APIs, and replaces pywrangler with wynd.
-
- {#- javascripts/system.js draws and animates the SVG #}
-
-
-
-
- Fig. 1 · How the packages fit together
-
- Python sits at the centre of Crosswind. Agents, Containers, Wynd and Workers connect to it. Wynd drops the dependencies a Worker never imports, packs the rest into a bundle and deploys it to Workers. Select a package in the diagram to open its docs.
-
-
-
Python deserves the full power of the edge.
-
One core. Four packages.
-
Each package does one job.
-
More of the edge. In Python.
-
- {#- Stacked layers, back to front (grid, routes, packages, logo, moving parts), so a frame only repaints the layers that changed #}
-
-
-
-
-
-
-
-
-
-
-
Select to open the docs
-
-
-
-
-
-
-
-
-
-
-
+
{% endblock %}
{% block scripts %}
{{ super() }}
+
+
{% endblock %}
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
index 3bd60ea..7953298 100644
--- a/docs/overrides/main.html
+++ b/docs/overrides/main.html
@@ -1,5 +1,11 @@
{% extends "base.html" %}
+{#- Material's font link asks for italics that Geist doesn't ship, so load the weights the theme uses #}
+{% block fonts %}
+
+
+{% endblock %}
+
{% block extrahead %}
-
-
- {#- javascripts/system.js draws and animates the SVG #}
-