# Semantic Braces
#
# A local contract for how brace-like notation can describe discoverable
# familiarity, nested meaning, and low-noise semantic jumping on spwashi.com.

#>spw_semantic_braces
#:semantics #!surface
#:layer #!pragmatics

^"grammar"{
  root: "The stable concept anchor. This is the thing that should resonate across instances."
  variant: "A distinguishable form of the root. Variants are siblings, not new roots."
  behavior: "An operational mode or affordance. Behaviors describe what the concept does."
  lens: "A reading lens or interpretive conduit. Lenses describe how the concept is being taken up."
  expression: "root[variant]{behavior}<lens>"
  rule: "If a surface can be understood without the suffix, the suffix should add a teachable distinction rather than decorative noise."
}

^"operator_physics"{
  brackets: "[] separate discoverable variants and support resonance across sibling forms."
  braces: "{} attach behavior, direction, or action to the root without changing the root."
  parens: "() stage scenes and performative contexts."
  angles: "<> carry lenses, conduits, or interpretive filters; in authored HTML, prefer data attributes or escaped text so markup stays valid."
  discoverability: "A reader should be able to jump from one instance to another by shared root, then narrow by variant or behavior."
}

^"operational_semantics"{
  definition: "Semantic braces participate in emergent cognitive+computational communication. They are cognitive scaffolds for human readers (familiarity, nesting, jumping) and computational handles (queryable via data attributes, claim-bearing, event-emitting)."

  cognitive_use: .{
    for_authors = "The expression syntax (root[variant]{behavior}<lens>) gives writers a precise way to signal how a concept should be taken up."
    for_learners = "Readers learn to navigate by root first, then refine by variant/behavior/lens — a transferable cognitive skill."
  }[reg=facet]

  computational_use: .{
    selectors = #[
      `[data-spw-semantic-root]`
      `[data-spw-semantic-expression]`
      `[data-spw-semantic-behavior]`
    ][reg=set]
    events = #[
      `spw:semantic-expression-expanded`
      `spw:semantic-match-found`
    ][reg=set]
    ownership = "semantic + runtime (brace-gestures, projection logic)"
  }[reg=facet]

  claims: .{
    braces_are_queryable: {
      claim_id = "semantic-braces-queryable-001"
      layer = "semantic"
      hypothesis = "Brace expressions must be readable from stable data attributes so agents and editors can query and validate semantic structure without parsing prose."
      spec_ref = ".spw/conventions/semantic-braces.spw#operational_semantics"
      impl_ref = "any element using data-spw-semantic-* attributes"
      probe_ref = "Design catalog or state inspector can list all instances of a given semantic-root or behavior."
      falsification = "A prominent semantic brace pattern exists only in raw text or classes with no machine-readable attributes."
      status = "active"
    }
  }[reg=facet]

  validation: "New use of semantic brace notation must expose the expression via data attributes and satisfy the queryability claim."
}

^"runtime_contract"{
  html_attributes: [
    "data-spw-semantic-expression",
    "data-spw-semantic-key",
    "data-spw-semantic-family",
    "data-spw-semantic-root",
    "data-spw-semantic-variant",
    "data-spw-semantic-behavior",
    "data-spw-semantic-lens"
  ]
  runtime_state: [
    "data-spw-inspect-semantic-expanded",
    "data-spw-inspect-semantic-focused",
    "data-spw-inspect-semantic-match"
  ]
  interaction_rule: "When a semantic family is expanded, matching instances may become visible together, but authored text remains the source of truth."
  scale_rule: "Use only high-signal concepts. Semantic braces should make navigation easier, not turn every repeated noun into a target."
}

^"learnability"{
  rule: "The same concept should look familiar across routes even when its role changes."
  use_cases: [
    "jump between same-root concepts on the page",
    "compare variant forms without flattening them",
    "attach behavior labels that help subvocalize a phrase while reading",
    "describe liminality or nesting without forcing prose to carry all the structure"
  ]
  counterexample: "A surface invents a new brace pattern for every page, so no one learns the grammar and nothing resonates."
}

^"gesture_charge_and_interaction_reflection"{
  ~#note: "Braces function as a novel, inspectable UI primitive: gestures accumulate charge and write rich state for reflection, learning, and replay."
  thesis: "Pointer (tap/hold/drag with primary/secondary button) and keyboard (tab/enter) gestures on brace targets produce differentiated charge and source data, enabling objective/subjective flow awareness, L/R distinction, and state reflection without external tooling."
  current: "brace-gestures.js tracks charging/active/armed/projecting/committed with CHARGE_BY_GESTURE values; writes data-spw-gesture, data-spw-charge, data-spw-gesture-source (pointer|keyboard), data-spw-gesture-button (centralized via setGesture with proper neutral-path cleanup for transient interaction metadata); projects to field --spw-field-* hormones and --charge. Resolved semantic attrs + liminality already flow from form/brace metadata."
  discoverable_gestures: "HTML may carry data-spw-interaction-contract plus per-gesture notes so tap, hold, drag/swipe, double-click, and keyboard consequences are readable before the user experiments. Runtime writes charge state; author markup names intent."
  extension_direction: "Charge buckets or intensities can vary by gesture source/button and by data-spw-brace (objective vs subjective) for distinct 'return values' or copy affordances. Braces thus serve as live mirrors of attentional physics and metacognitive position."
  collection_alignment: "Committed or armed gestures on a brace carrying a semantic expression now emit a primed capture (primedBy: 'brace-containment-charge'). Double-click on semantic brace targets inspects and primes without waiting. The local value held by the containment becomes a gatherable cauldron ingredient with origin context. This makes cauldron collection discoverable from the same containment gestures used for inspection and pinning."
  aligns_with: "liminality axes, operator-as-sigil, cognitive-navigation dimensions, attention-field projection, privacy-centric local state (no server roundtrips), cauldron gathering phases, spell:capture bus"
}

@site_semantics: ~"./site-semantics.spw"
@operator_semantics: ~"./operator-semantics.spw"