Docs/language specification framework

fastn.com/CLAUDE.md

@@ -0,0 +1,98 @@
+# Claude Instructions for fastn.com
+
+## Testing FTD Files
+
+**IMPORTANT**: Before committing any changes to `.ftd` files in this repository:
+
+1. **Use RELEASE mode fastn only**:
+   - **ALWAYS** build fastn from source:
+     ```bash
+     cd /Users/amitu/Projects/fastn
+     cargo build --release --bin fastn
+     cp target/release/fastn ~/.cargo/bin/fastn
+     ```
+   - Only use `~/.cargo/bin/fastn` (release build from local source)
+   - **NEVER** use debug builds as they are unstable and will crash
+   - **NEVER** use `cargo install fastn` (gets wrong package from crates.io)
+   - The installation script binary may have dependency issues - use local source
+
+2. **Start the fastn development server**:
+   ```bash
+   cd fastn.com
+   ~/.cargo/bin/fastn serve --port 8001
+   ```
+
+2. **Test your changes in browser**:
+   - Open the modified pages in browser via `http://127.0.0.1:8001/path/to/your/file`
+   - Ensure the page loads without compilation errors
+   - Check that all content renders correctly
+   - Verify any components or imports work as expected
+
+3. **Common paths to test**:
+   - Language spec: `http://127.0.0.1:8001/language-spec/`
+   - FTD components: `http://127.0.0.1:8001/ftd/audio/` 
+   - New documentation: `http://127.0.0.1:8001/your-new-path/`
+
+4. **Fix any compilation errors**:
+   - Check the fastn server output for error messages
+   - Common issues: missing imports, incorrect syntax, circular imports
+   - Test changes iteratively until they work
+
+5. **Only commit after successful testing**
+
+## Common FTD Patterns
+
+- Use existing imports like `fastn.com/assets` and design system components
+- Check existing files for proper component structure and naming
+- Follow the established documentation patterns in `/ftd/` directory
+
+## Lint/TypeCheck Commands
+
+None specifically required for FTD files - the fastn server will catch syntax errors.
+
+## FTD Common Mistakes Cheat Sheet
+
+### ❌ Most Common Errors and Solutions
+
+**1. Mismatched Section Ends**
+```
+Error: "No section found to end: component-name"
+```
+**Cause**: Unmatched `-- end:` statements in code blocks or missing escape
+**Fix**: Escape end statements in code blocks: `\-- end: component-name`
+
+**2. Wrong Type References**
+```
+Error: "fastn.type.heading-large not found"
+```
+**Cause**: Using `$fastn.type.*` instead of `$inherited.types.*`
+**Fix**: Use `$inherited.types.heading-large` not `$fastn.type.heading-large`
+
+**3. Component Attribute Not Found**
+```
+Error: "Header type 'preload' not found for component 'ftd.audio'"
+```
+**Cause**: Using unsupported attributes for components
+**Fix**: Check existing component docs, only use supported attributes
+
+**4. Unescaped Code in Examples**
+```
+Error: Section parsing errors in code blocks
+```
+**Cause**: FTD code in `-- ds.code:` blocks needs escaping
+**Fix**: Escape FTD syntax: `\-- ftd.text:` not `-- ftd.text:`
+
+**5. Custom Components Don't Exist**
+```
+Error: "terminal-output not found"
+```  
+**Cause**: Using imaginary components like `ds.terminal-output`
+**Fix**: Stick to documented `ds.*` components or build custom ones
+
+### ✅ Quick Fixes
+
+- **Always test pages**: `curl http://127.0.0.1:8004/path/` before committing
+- **Start simple**: Create minimal working version, then add complexity
+- **Check nesting**: Count `-- ftd.column:` vs `-- end: ftd.column` statements
+- **Use existing patterns**: Copy structure from working files like `/ftd/text.ftd`
+- **Escape examples**: Use `\--` in all code blocks showing FTD syntax

fastn.com/FASTN.ftd

@@ -615,6 +615,9 @@ skip: true
 
 # Docs: /ftd/data-modelling/
 
+-- FTD 0.4 Language Specification: /spec/
+  document: spec/index.ftd
+
 ## `fastn` Made Easy: /book/
 
 - Introduction: 

fastn.com/spec/components/index.ftd

@@ -0,0 +1,18 @@
+-- ds.page: Components
+
+Component definition, invocation, and usage in FTD
+
+-- ds.h1: Component Definition
+
+Components are reusable building blocks defined with the `component` keyword.
+
+-- ds.h1: Component Usage
+
+Components are invoked like sections with optional captions and properties.
+
+-- ds.code: Component Examples
+lang: ftd
+
+\-- ftd.text: Hello World
+\-- custom-component: With Caption
+property: value

fastn.com/spec/functions/index.ftd

@@ -0,0 +1,54 @@
+-- ds.page: Functions
+
+Function definitions, calls, expressions, and built-in functions in FTD
+
+-- ds.h1: Function Definition
+
+Functions encapsulate reusable logic and can accept parameters.
+
+-- ds.code: Basic Function
+lang: ftd
+
+\-- string greeting(name):
+string name:
+
+Hello $name! Welcome to fastn.
+
+-- ds.h1: Function Calls
+
+Functions are called using standard invocation syntax.
+
+-- ds.code: Function Usage
+lang: ftd
+
+\-- ftd.text: $greeting("Alice")
+\-- ftd.text: $greeting("Bob")
+
+-- ds.h1: Function Parameters
+
+Functions can accept multiple typed parameters.
+
+-- ds.code: Multi-Parameter Function
+lang: ftd
+
+\-- string format-price(amount, currency):
+decimal amount:
+string currency:
+
+$currency $amount
+
+\-- ftd.text: $format-price(29.99, "USD")
+
+-- ds.h1: Built-in Functions
+
+FTD provides several built-in functions for common operations.
+
+-- ds.code: Built-in Function Examples
+lang: ftd
+
+\-- string upper-name: $upper($name)
+\-- string formatted: $format("{}: {}", "Name", $name)
+\-- integer length: $len($name)
+
+\-- ftd.text: $upper-name
+\-- ftd.text: Length: $length

fastn.com/spec/index.ftd

@@ -0,0 +1,82 @@
+-- ftd.column:
+spacing.fixed.px: 24
+width: fill-container
+
+-- ftd.text: FTD 0.4 Language Specification
+role: $inherited.types.heading-large
+color: $inherited.colors.text-strong
+
+-- ftd.text: Complete specification for the fastn Template Definition (FTD) language version 0.4
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+-- ftd.text: 
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+This comprehensive language specification covers all aspects of FTD 0.4, providing
+developers with the definitive reference for fastn template development.
+
+-- ftd.column:
+spacing.fixed.px: 32
+width: fill-container
+margin-top.px: 32
+
+-- spec-section: Syntax
+url: /spec/syntax/
+description: Core syntax rules, sections, headers, comments, and complete BNF grammar
+
+-- spec-section: Types  
+url: /spec/types/
+description: Primitive types, built-in types, records, or-types, and type inference rules
+
+-- spec-section: Components
+url: /spec/components/
+description: Component definition, invocation, arguments, children, and inheritance
+
+-- spec-section: Variables
+url: /spec/variables/
+description: Variable declaration, scoping rules, mutability, and references
+
+-- spec-section: Functions
+url: /spec/functions/
+description: Function definitions, calls, expressions, and built-in functions
+
+-- spec-section: Modules
+url: /spec/modules/
+description: Import semantics, export rules, aliases, and package system
+
+-- end: ftd.column
+
+-- end: ftd.column
+
+-- component spec-section:
+caption title:
+string url:
+string description:
+
+-- ftd.column:
+spacing.fixed.px: 8
+width: fill-container
+padding.px: 24
+border-width.px: 1
+border-color: $inherited.colors.border
+border-radius.px: 8
+background.solid: $inherited.colors.background.step-1
+
+-- ftd.text: $spec-section.title
+role: $inherited.types.heading-medium
+color: $inherited.colors.text-strong
+
+-- ftd.text: $spec-section.description
+role: $inherited.types.copy-regular
+color: $inherited.colors.text
+
+-- ftd.text: → Explore
+role: $inherited.types.copy-regular
+color: $inherited.colors.accent.primary
+margin-top.px: 8
+
+-- end: ftd.column
+
+-- end: spec-section

fastn.com/spec/modules/index.ftd

@@ -0,0 +1,35 @@
+-- ds.page: Modules
+
+Import semantics, export rules, and package system in FTD
+
+-- ds.h1: Import Statements
+
+Modules are imported at the top of files.
+
+-- ds.code: Basic Imports
+lang: ftd
+
+\-- import: some-package
+\-- import: ui-components
+\-- import: design-system as ds
+
+-- ds.h1: Import Aliases
+
+Modules can be imported with aliases.
+
+-- ds.code: Aliased Imports
+lang: ftd
+
+\-- import: long-package-name as short
+
+\-- short.component: Using alias
+
+-- ds.h1: Exports
+
+Modules expose components and functions through exports.
+
+-- ds.code: Export Examples
+lang: ftd
+
+\-- export: my-component
+\-- export: my-function

fastn.com/spec/syntax/comments.ftd

@@ -0,0 +1,26 @@
+-- ds.page: Comment Syntax
+
+Single-line and multi-line comment syntax in FTD
+
+-- ds.h1: Single-Line Comments
+
+Single-line comments begin with `;;` and continue to the end of the line.
+
+-- ds.code: Comment Examples
+lang: ftd
+
+;; This is a comment
+\-- ftd.text: Hello World ;; Inline comment
+color: red ;; Another comment
+
+-- ds.h1: Comment Placement
+
+Comments can be placed in various locations within FTD documents.
+
+-- ds.code: Comment Placement
+lang: ftd
+
+;; File-level comment
+\-- ftd.text: Content
+;; Before properties  
+color: blue ;; After values