[WillEhrendreich]

Binds Datastar 1.0.4 and adds a typed layer for signals, expressions and statements, plus server-side helpers for Rocket components.

Every claim in the README about Datastar's behaviour was checked against the v1.0.4 source rather than against its documentation, and a few of the things that were documented before turned out to be wrong. Those are the reason for most of the output changes below.

What is new

A typed layer. Signal.browser, Signal.server, Signal.rocket, Expr and Stmt let the compiler check what a JavaScript string cannot: that a signal exists, that a condition is a boolean, and that a value has the type of its signal. The string helpers are unchanged and still there.

let count = Signal.browser<int> "count"
let name  = Signal.server<string> "form.name"

Elem.div [ Ds.signal (count, 0); Ds.bind name ] [
    Elem.button [ Ds.onClick (Stmt.set count (Expr.add (Expr.read count) (Expr.int 1))) ] [ Text.raw "+" ]
    Elem.span [ Ds.text (Expr.read count) ] []
]

Rocket helpers for what a server renders: props with the codec each component expects, component-scoped signals, and the template directives. Rocket is in beta upstream and this follows its current shape.

Request helpers for reading signals, and a Response module covering the Server Sent Events.

Output that changes, and why

These are the ones worth reading. Each was checked against Datastar's source, and each was wrong or silently ineffective before.

Ds.setAll and Ds.toggleAll did nothing at all. They wrote @setAll('foo.', true). Datastar's signature is apply(_, value, filter) and toggleAll takes only a filter, so the prefix was being taken as the value and the value as the filter. They now write @setAll(true, { include: /^foo\./ }) and @toggleAll({ include: /^foo\./ }). The prefix is escaped as well, so a prefix containing a regex character now matches literally.

Ds.safariStreamingFix never fired. It wrote data-on:pageshow.window; Datastar has read modifiers after __ since 1.0.0, so it was listening for an event called pageshow.window.

Retry was ignored, because it was never written. Retry = OnError, OnAlways and OnNever now reach Datastar, so a request that sets one behaves differently.

RetryMaxWait was ignored too, under the name retryMaxWaitMs, which Datastar stopped reading in 1.0.0. It is now retryMaxWait.

FilterSignals raised JsonReaderException for any pattern, because the filter was written as if it were JSON. It is now {"filterSignals":{"include":"^foo"}}.

ContentType = CustomJson sent the wrong key. It wrote override, which Datastar does not have, so the signals went as usual. It now sends payload.

AbortController "$ctl" was sent as the text "$ctl", which Datastar ignores, because Datastar wants the controller object itself rather than its name. It is now written as $ctl, so the expression reads the signal that holds the controller.

Text is escaped. Ds.get, Ds.post and the rest escape the URL, Ds.signal escapes its value, and Ds.ref did not escape at all, so a name containing a quote ended the attribute and added attributes of its own. A name with no quote, angle bracket or ampersand renders exactly as before.

Names are checked. A signal name that Datastar would read differently from an expression, and a name that could end an attribute name early, now raise an ArgumentException that says what to write. This is new behaviour on input that used to be accepted, and Ds.class' ("card__title", …) is refused: Datastar reads that as a class called card with a modifier title.

OpenWhenHidden is now bool voption. It used to default to false and never be sent, so a @post got Datastar's true anyway. Leaving it unset now means Datstar's per-method default applies.

Breaking changes

• OpenWhenHidden = true becomes OpenWhenHidden = ValueSome true.
• Passing an argument whose type is not yet known, such as let click handler = Elem.button [ Ds.onClick handler ] [] or List.map Ds.show, now fails with FS0041. Add a type annotation. The typed overloads are new, so no released code is affected.
• BackendAction.Query, RequestCancellation.Cleanup and OnEventModifier.Document are new union cases, so an exhaustive match gets warning FS0025.
• Signal.tryCreate returns a SignalNameError rather than text, and RocketManifest.parse and Request.getRocketManifests return a RocketManifestError.
• SignalPath.getSignalFromJson still returns ValueNone for a value it cannot read, as it always has.
• A Signal.rocket is refused by Ds.signal, Ds.bind, Ds.computed and Ds.indicator. Rocket scopes an attribute's signal name to one component only for a signal that component declared with $$('name', value) in its setup, so anywhere else the name quietly meant a page signal that two components would share. Inside a component, use Rocket.local, or declare the signal there and bind to it with Ds.bind "name".

Testing

• 329 unit tests on net8.0, net9.0 and net10.0.
• Named tests pin the output of every helper.
• Property tests (FsCheck) cover the rules the library's reasoning rests on: escaping round-trips, signal names Datastar reads as written, and the parentheses that keep a neighbouring operator out of an expression.
• Simulation tests are seeded, so a failure replays, and build hostile text that an HTML5 parser reads back. DST_SEEDS=2000 for a long sweep.
• Mutation tests (test/mutation) make a deliberate mistake in the source and require the suite to notice. 98 mutants, and the run prints how much of the library they rewrite so "all killed" is not read as more than it is. Mutation runs cannot be generated here, because no tool supports F#, so the list is hand-written and check verifies every entry still matches the source.
• 19 browser tests drive real Chromium against Datastar 1.0.4 loaded from the CDN.

CI builds the solution, fails on any warning, type-checks every F# example in the README and the changelog against the built library, and checks the package contents. The mutation and DST runs also run on a schedule, so a claim about the tests cannot quietly rot.

What I would want reviewed

• The escaping rules in Utility.fs are the security boundary, since Falco.Markup does not escape attribute values or names. I would like a second opinion on Js and Guard specifically.
• The signal-name rules in Expr.fs. They refuse names for reasons that come from Datastar's parser; if any of those reasons is wrong the rule is wrong with it.
• Rocket is in beta upstream, so Rocket.fs may need to move with it.

[Copilot]

Copilot review overview

🟡 Changes recommended

Rocket signal scoping is implemented from an incorrect upstream premise, with additional escaping, parsing, API-safety, and test-harness defects.

Review effort: Balanced
Findings: 1 · 10 · 6

Open (17)

• Reject malformed UTF-8 during manifest decoding · New
• Allow typed component-local signal attributes · New
• Enforce numeric constraints for arithmetic signals · New
• Restrict prop values to supported numeric types · New
• Reject malformed optional property types · New
• Use culture-invariant case-insensitive replacements · New
• Escape line separators after backslashes · New
• Update tests to allow local signal attributes · New
• Preserve selected fragment group indices · New
• Compile all documentation blocks or mark excerpts · New
• Drain stdout and stderr concurrently · New
• Remove contributor-specific assistant profile files · New
• Correct inaccurate upgrade behavior note · New
• Update example to use the current component API · New
• Correct README guidance on typed local signals · New
• Document automatic prop name kebab-casing · New
• Correct signal setup restriction documentation · New

What changed in this PR

Updates Falco.Datastar for Datastar 1.0.4 with typed APIs, Rocket support, corrected request behavior, and expanded verification.

Changes:

• Adds typed signals, expressions, statements, and Rocket helpers.
• Adds Rocket manifest parsing and request handling.
• Expands unit, property, simulation, mutation, browser, documentation, and CI checks.

File	Description
.commandcode/​taste/​taste.md	Adds assistant-profile pointer.
.commandcode/​taste/​taste/​taste.md	Adds contributor-specific assistant profile.
.github/​workflows/​build.yml	Expands build, test, documentation, and package checks.
.github/​workflows/​dst.yml	Adds scheduled simulation tests.
.github/​workflows/​e2e.yml	Adds on-demand browser tests.
.github/​workflows/​mutation.yml	Adds scheduled mutation testing.
CHANGELOG.md	Documents 1.4.0 behavior and migration.
Falco.Datastar.sln	Adds the Rocket example and fixes path casing.
README.md	Documents typed and Rocket APIs.
examples/​RocketComponents/​RocketComponents.fs	Implements the Rocket example application.
examples/​RocketComponents/​RocketComponents.fsproj	Defines the example project.
examples/​RocketComponents/​appsettings.json	Configures the example host.
src/​Falco.Datastar/​Ds.fs	Adds typed overloads and corrected Datastar helpers.
src/​Falco.Datastar/​Expr.fs	Implements typed signals, expressions, and statements.
src/​Falco.Datastar/​Falco.Datastar.fsproj	Updates package version and source dependencies.
src/​Falco.Datastar/​Request.fs	Adds Rocket manifest request reading.
src/​Falco.Datastar/​Rocket.fs	Adds server-side Rocket helpers.
src/​Falco.Datastar/​RocketManifest.fs	Parses Rocket manifests.
src/​Falco.Datastar/​Types.fs	Extends request options and attribute types.
src/​Falco.Datastar/​Utility.fs	Adds escaping, validation, and kebab conversion.
test/​Falco.Datastar.E2E/​BrowserFixture.fs	Hosts shared browser and example fixtures.
test/​Falco.Datastar.E2E/​BrowserTests.fs	Exercises behavior in Chromium.
test/​Falco.Datastar.E2E/​Falco.Datastar.E2E.fsproj	Defines the browser-test project.
test/​Falco.Datastar.E2E/​Program.fs	Adds the test executable entry point.
test/​Falco.Datastar.E2E/​README.md	Documents browser testing.
test/​Falco.Datastar.E2E/​Site.fs	Provides browser-test pages and endpoints.
test/​Falco.Datastar.Tests/​CompatibilityTests.fs	Compile-checks compatibility promises.
test/​Falco.Datastar.Tests/​DistributionTests.fs	Checks simulation-generator distributions.
test/​Falco.Datastar.Tests/​DsTests.fs	Expands helper output tests.
test/​Falco.Datastar.Tests/​Dst.fs	Adds deterministic simulation orchestration.
test/​Falco.Datastar.Tests/​DstHtmlTests.fs	Simulates hostile HTML inputs.
test/​Falco.Datastar.Tests/​DstManifestTests.fs	Simulates malformed manifests and streams.
test/​Falco.Datastar.Tests/​EscapingTests.fs	Tests escaping boundaries.
test/​Falco.Datastar.Tests/​ExprTests.fs	Tests typed expressions and statements.
test/​Falco.Datastar.Tests/​Falco.Datastar.Tests.fsproj	Expands frameworks and test dependencies.
test/​Falco.Datastar.Tests/​Fragments.fs	Defines weighted hostile inputs.
test/​Falco.Datastar.Tests/​Generator.fs	Implements deterministic SplitMix64 generation.
test/​Falco.Datastar.Tests/​GeneratorTests.fs	Pins generator behavior.
test/​Falco.Datastar.Tests/​PropertyTests.fs	Adds property-based invariants.
test/​Falco.Datastar.Tests/​README.md	Documents the test strategy.
test/​Falco.Datastar.Tests/​RequestOptionsTests.fs	Tests corrected request serialization.
test/​Falco.Datastar.Tests/​RequestTests.fs	Tests request signal reading.
test/​Falco.Datastar.Tests/​ResponseTests.fs	Tests SSE response helpers.
test/​Falco.Datastar.Tests/​RocketManifestTests.fs	Tests manifest parsing and limits.
test/​Falco.Datastar.Tests/​RocketTests.fs	Tests Rocket rendering helpers.
test/​Falco.Datastar.Tests/​TestHelpers.fs	Adds shared test utilities.
test/​mutation/​Mutants.fs	Defines mutation cases.
test/​mutation/​Program.fs	Adds mutation-runner CLI handling.
test/​mutation/​Runner.fs	Runs and restores source mutations.
test/​mutation/​mutation.fsproj	Defines the mutation project.
test/​readme-examples.fsx	Type-checks documentation examples.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[WillEhrendreich]

All 17 findings addressed and each thread answered and resolved. Summary of what changed, and one correction worth reading first.

The Rocket scoping finding was right and my original reasoning was wrong.

I had refused Signal.rocket in Ds.signal/bind/computed/indicator on the premise that Rocket only scopes a signal the component declared with $$('name', value). Reading rewriteDataAttributes in library/src/rocket/template.ts at v1.0.4 shows the lookup in localSignals is not a gate: it falls through to prefixing with signalPathBase either way. My earlier reading stopped at the lookup and missed the fallthrough, so the refusal was removing working behaviour and the README told people to do something they did not need to do. The refusal is gone, the tests that encoded it now assert the rendered output, and the actual requirement — that a component be rendered — is documented rather than refused.

The rest, all verified against the Datastar v1.0.4 source before changing anything:

Area	Fix
Manifest decoding	Malformed UTF-8 is rejected instead of decoded with replacement characters
Arithmetic	INumberBase<'T> instead of IFormattable, so DateTime/Guid/string are compile errors
propNumber	Non-finite values refused; JavaScript Number(...) would have turned them into 0
Manifest optionals	A wrong-typed field is reported as wrong, not silently read as absent
Kebab conversion	Culture-invariant, matching JavaScript under a Turkish locale
Regex escaping	U+2028/2029 escaped after a backslash, which is the position that matters
Fragment distribution	Generation carries the chosen group index, so measured weights match configured
Documentation examples	See below

The documentation-example check was not checking anything, in two ways.

It only inspected blocks beginning with let, so 58 of 71 README blocks were skipped while the run still printed how many it had checked. And it ran each block with dotnet fsi --use:, which loads and evaluates the file — the getting-started example called .Run(), bound port 5000, and the process hung there. That is where the half-hour runtime came from; it was never compiler startup cost.

It now compiles each block with fsc, which never evaluates, so an example that starts a web server costs nothing. Each block is compiled alone, so a block that only compiles because an earlier one defined a name fails. A failure now exits nonzero, and a floor on the block count fails the build, so this cannot quietly go back to checking nothing.

Turning it on found three real mistakes in the README: a stray leading space in a code block, and two fragments missing an open. Eleven fragments genuinely cannot stand alone — they continue an example above them — and each now says so in a README-EXCERPT comment with the reason, printed on every run.

Verification. 335 tests green on net8.0, net9.0 and net10.0; 19 browser tests green in Chromium; solution builds with no warnings outside the NuGet advisories the project deliberately allows; package gate reads the built .nupkg; 98 mutants validate; every documented example compiles. The example checker was confirmed by breaking an example and checking that it fails, rather than by the run passing.

One caveat worth stating: the full mutation run (all 98 mutants killed, roughly 25 minutes) has not been re-run since e5ab4fd; the fast check passes and the full suite runs on the weekly schedule.

[WillEhrendreich]

Follow-up: the full mutation run finished, so this is no longer resting on the weekly schedule.

96 of 98 killed. The other two are not test gaps — they are mutations the code genuinely cannot be told apart from the original, and I investigated both rather than writing tests that claim to catch them.

a response starts the stream twice — the SDK's StartServerEventStreamAsync is idempotent. Its state machine assigns ContentType and CacheControl rather than appending, so a second call leaves one value in the header collection, writes nothing to the body, and throws nothing. Measured against the real SDK, all three are identical after one call and after two.

Worth recording honestly: I first wrote a test for this that counted header values, and it killed the mutant — but only because the task had not been awaited yet. Once awaited, the count stayed at 1 and the test would have passed for entirely the wrong reason. I did not keep it. A green test that catches a bug by accident is worse than an honest survivor.

ofRemoveElementOptions ignores the options the caller passed — RemoveElementOptions has exactly one field, EventId, and a removal event carries no id. Confirmed by compiling a record update naming a field the SDK does not have (rejected) and by reading the bytes the SDK writes. The existing test already asserts there is no id on a removal, so passing the options and dropping them produce identical wire output. The overload still passes them.

Both are now marked equivalent in the mutant list with the measurement as evidence, so future runs report them as such rather than as outstanding work. All 98 mutations are accounted for.

Everything else re-verified after the change: 335 tests green on net8.0/net9.0/net10.0, solution builds with no warnings outside the NuGet advisories the project allows, all 63 documented examples compile, mutant list validates.