docs: consolidate legacy specs and rigorously detail declarative action framework mechanics

Author: Corey B

Formatted Data Document Open Spec.md

@@ -1,56 +1,97 @@
 # The Formatted Data Document (.fdd) Specification v1.1
 
-## 1. File Structure overview
-An `.fdd` file is structurally a Single-File Web App (SWA) consisting of distinct blocks forming the boundaries of the container. The overall boundary of an `.fdd` file is text-based HTML but relies on strict internal regions.
+## 1. Architectural Philosophy
+An `.fdd` file is a "Local-First" interactive container. It treats the browser as an OS, allowing for a zero-infrastructure application experience where the file *is* the state. A document should not be a static printed picture of data (like a PDF), but rather a structured data payload wrapped seamlessly in presentation logic, natively capable of persisting its own user-driven mutations.
 
-No `<script>` elements with active javascript execution are permitted. The `.fdd` viewer MUST block executable JavaScript execution.
+## 2. File Structure & Anatomy
+An `.fdd` file is structurally a Single-File Web App (SWA) bounded by an `<fdd-container>` wrapper. The document strictly enforces a **No-JS Security Model**. Authors are entirely forbidden from loading or executing native `<script>` logic.
 
-### The Anatomy of an `.fdd` Container
+### 2.1 The Data Segregation Model
+To allow for "Protected Data" alongside "Mutable Notes," FDD enforces a layered integrity architecture based on `id` routing:
 
 ```html
 <fdd-container extension=".fdd">
-  <!-- 1. Integrity Block & Semantic Core -->
+  <!-- 1. Integrity Block (Cryptographically Secure) -->
   <script type="application/vc+json" id="fdd-data">
-    ... Cryptographically signed JSON-LD / Verifiable Credentials ...
+    {
+      "issuer": "...",
+      "credentialSubject": { "accountBalance": "5200.00" },
+      "proof": { "signature": "..." }
+    }
   </script>
 
-  <!-- 2. Local State Block (Mutable) -->
+  <!-- 2. Local State Block (User-Writeable) -->
   <script type="application/json" id="user-notes">
-    ... User-writeable JSON state ...
+    { "followUp": "Call regarding interest rates", "contacts": [] }
   </script>
 
-  <!-- 3. Template Layer -->
+  <!-- 3. Presentation Layer & Bindings -->
   <template shadowrootmode="open" bind="#fdd-data, #user-notes">
-    ... UI relying on Declarative Shadow DOM & CSS ...
+    ... Declarative HTML UI ...
   </template>
 </fdd-container>
 ```
 
-## 2. Integrity & Sovereignty (The Signing Model)
+## 3. The Declarative Action Framework
+To allow developers and AI models to build complex, reactive applications (like CRMs or banking dashboards) without violating the No-JS security constraints, OpenFDD relies on a standardized set of declarative HTML actions parsed natively by the `fdd.js` wrapper execution engine.
 
-The FDD container enforces a **Layered Signature Model** inside the `<fdd-container>`.
+### 3.1 Template Data Binding
+The presentation `<template>` is evaluated using lightweight mustache-syntax against the merged dictionaries of `#fdd-data` and `#user-notes`.
+*   **Property Binding:** `<h1>{{accountBalance}}</h1>`
+*   **Array Iteration:** Use `{{#each arrayName}}` to iterate over nested objects. Within an iterative loop, the parser natively routes the `{{@index}}` tag to identify the active object's array index natively.
 
-1.  **Verified Block (Read-Only):** Using W3C Verifiable Credentials (VC) standard, this JSON-LD core (e.g., `<script type="application/vc+json">`) is signed using Ed25519 (or similar verifiable methods). If any bit of the data payload is altered, it breaks the signature.
-2.  **Mutable Block (User-Writeable):** A separate JSON state block (`<script type="application/json">`) is unsigned and designed for continuous user interaction (e.g. form fields, CRM notes).
-3.  **Wrapper Signature:** An optional JWS across the `fdd-container` DOM that validates the *Template Layer* hasn't been modified to perform phishing attacks or hide critical information via CSS.
-
-## 3. The "Self-Saving" Mechanism (Persistence)
-
-An `.fdd` file acts as its own state database. Updates to the DOM natively sync back to the originating `.fdd` file on disk relying on unified persistence strategies.
-
-*   **Primary Strategy (File System Access API):** The `.fdd` parser bounds interactive changes to an explicit write-lock approval prompt on execution. If granted, mutable components actively rewrite the local file.
-*   **Universal Fallback (The Save Pattern):** Because native write-locks are routinely restricted (e.g., Linux sandbox environments), the FDD specification standardizes a uniform "Save Updates" interface. When active edits mutate the DOM, a persistent prompt alerts the user. Committing the save leverages ambient URI hooks to default the OS download to exactly match the originating `.fdd`'s filename and route.
-
-## 4. No-JS Security Model
-Since executable scripts are blocked, interactions scale through:
-*   **CSS Pseudo Types:** Hover actions, transitions, toggle elements (`:checked`).
-*   **Declarative Extensions:** Custom native UI parsers implementing explicit handlers like `[autosave]` or `[fdd-push]`.
-
-### 4.1 The "Hidden Ink" Presentation Risk
-Because OpenFDD relies on declarative CSS for structural templating, there exists an inherent UI spoofing vector (e.g., matching text color to background color or using `display: none` to conceal contractual terms from the reader). 
-
-To proactively mitigate this, OpenFDD formally separates the **Integrity Layer** (`#fdd-data`) from the **Presentation Layer** (`<template>`). 
-*   Authoritative `.fdd` viewers, parsing libraries, and browser extensions **SHOULD** proactively implement accessibility contrast safeguards (evaluating stylesheets to prevent exact background-hex mappings), OR they must provide a baseline "Raw Data Inspector" UI. This guarantees users can definitively read the pristine, un-styled JSON presentation block.
-*   If a discrepancy arises between the layout masking and the JSON block, the guiding principle of the specification dictates: **The Presentation is merely a convenience; the raw cryptographically signed data block remains the indisputable source of truth.**
+```html
+{{#each contacts}}
+<div class="card">
+  <h2>{{name}}</h2>
+  <button fdd-action="delete" fdd-target="user-notes.contacts" fdd-index="{{@index}}">Delete</button>
+</div>
+{{/each}}
+```
 
-## 5. Deployment Ecosystem
+### 3.2 State Mutations & Interactions
+The parser intercepts standard DOM elements annotated with `fdd-target` attributes explicitly mapping back to the mutable `#user-notes` JSON block. (Mutations targeting `#fdd-data` will trigger native compilation warnings and fail silently during run-time execution to protect cryptographic signature thresholds).
+
+*   **Auto-Save Inputs:** Appending the `autosave` attribute to an `<input>` or `<textarea>` maps real-time keystrokes securely back to the file state.
+    *   `<textarea name="user-notes.followUp" autosave>{{followUp}}</textarea>`
+*   **Array Pushes:** Standard HTML forms perfectly interact with FDD schemas to append structured objects into an array securely without scripts.
+    *   `<form fdd-action="push" fdd-target="user-notes.contacts">`
+*   **Property Setters:** Custom `<button>` elements can declaratively rewrite explicit local variables or deep-nested objects.
+    *   `<button fdd-action="set" fdd-target="user-notes.contacts.{{@index}}.archived" fdd-value="true">Archive Contact</button>`
+
+### 3.3 Ephemeral State & Conditional Routing (The UI-State)
+To track complex "Transient View State" (like actively modifying a contact card or swapping pages) without routinely spamming the user's hard-drive, OpenFDD provides an ephemeral rendering router detached entirely from the persistent `#user-notes` schema: `ui-state`.
+
+*   **Setting Active View State:** `<button fdd-action="set-ui" fdd-target="selectedTab" fdd-value="contacts">`
+*   **Deep Contextual Rendering Layouts:** Use `fdd-match` to explicitly isolate deep layout injections strictly to the target UI route!
+    ```html
+    <div class="editor" fdd-match="ui.selectedTab" fdd-value="contacts">
+        <!-- Renders ONLY when that specific UI state matches without firing Save Warnings -->
+    </div>
+    ```
+*   **Conditional Pruning:** Explicit boolean DOM exclusions are natively built into the standard mapping loop logic:
+    *   `<span fdd-if="{{isVerified}}">Certified</span>`
+    *   `<span fdd-unless="{{archived}}">Active Pipeline Target</span>`
+
+## 4. The Self-Saving Persistence Mechanism
+An `.fdd` file acts as its own state database. Updates to the DOM efficiently sync back to the originating `.fdd` file natively.
+
+*   **Primary Strategy (File System Access API):** The `.fdd` parser bounds interactive changes to an explicit file-handle write-lock approval prompt on initial layout bounds. If granted, mutable components actively rewrite the local file.
+*   **Universal Fallback (The Save Pattern):** Because native write-locks are routinely restricted (e.g., Linux sandbox environments / URI contexts), the FDD specification standardizes a uniform "Save Updates" interface overlay. When active edits mutate the DOM, a persistent prompt alerts the user without interfering in the UI layout. Committing the respective save actively leverages ambient location hooks to definitively default the internal OS download to actively match the originating `.fdd`'s explicit filename!
+
+## 5. Security Model & The Hidden Ink Risk
+Since executable scripts are stripped, interactions scale solely through CSS Pseudo Types (`:checked`, `:hover`) and the rigid Declarative Action framework documented above.
+
+### 5.1 The "Hidden Ink" Presentation Risk
+Because OpenFDD utilizes declarative CSS for structural templating, there inherently exists a layout spoofing vector (e.g., deliberately matching text properties to background bounds, or hiding blocks via `display: none` to actively conceal contractual obligations). 
+
+To heavily mitigate this vector, OpenFDD formally separates the **Integrity Layer** (`#fdd-data`) from the loosely defined **Presentation Layer** (`<template>`). 
+*   Authoritative `.fdd` viewers **SHOULD** proactively implement accessibility contrast safeguards, OR securely expose a persistent "Raw Data Inspector" UI guaranteeing immediate visibility towards the un-styled, pristine JSON structure.
+*   **The Governing Principle:** Presentation is merely a convenience; the raw cryptographically signed `#fdd-data` layer asserts the absolute legal source of truth.
+
+## 6. The Advocacy Roadmap
+To establish `.fdd` ubiquity across browsers and SaaS ecosystems:
+1. **The "Trust Tier" Proposal:** Lobby W3C/WICG to explicitly configure Zero-JS containers securely to bypass the rampant "Permission Fatigue" common among local-first web app strategies.
+2. **The "AI Grounding" Certification:** Forcefully position `.fdd` outputs as the prime injection metric for generative LLMs structure mapping, aggressively supplanting hallucinatory OCR-bound PDF scrapes with cryptographically pristine JSON-LD payloads.
+3. **SaaS "Off-Ramp" Continuity:** Persuade leading core Enterprise architectures (Hubspot/Salesforce) to route client exports into highly interactive `.fdd` single-file-apps rather than static, un-recyclable PDF forms.
+4. **The Safe Universal Reader:** Systematically deploy a highly accessible PWA handler catching default OS interactions while strategically routing telemtry insights towards browser vendor implementations natively.