@hviana/sema 0.1.6 → 0.1.8

package/dist/src/mind/traverse.d.ts

@@ -16,6 +16,19 @@ export declare function edgeAncestors(ctx: MindContext, id: number, contextCount
 export declare function nextOf(ctx: MindContext, id: number): number[];
 /** Convenience: reverse edges of a node. */
 export declare function prevOf(ctx: MindContext, id: number): number[];
+/** The uniform-expectation floor on a byte atom's corpus commonality: N
+ *  learnt contexts, each at least one perception chunk of up to W of the 256
+ *  possible byte values, contain a given atom in ≥ N·W/256 contexts on
+ *  average.  An atom's TRUE containment is unmeasurable (atoms carry no
+ *  kid/contain links by construction), so this floor is the honest stand-in:
+ *  derived entirely from the corpus scale N, the perception window W, and
+ *  the alphabet size — never tuned. */
+export declare function atomReach(ctx: MindContext, contextCount: number): number;
+/** Whether a byte atom is a hub at this corpus scale — its commonality floor
+ *  {@link atomReach} exceeds the hub bound √N.  Below it (small stores) an
+ *  atom votes and is recognised exactly as any stored form; above it the
+ *  alphabet is scaffolding everywhere and abstains. */
+export declare function atomIsHub(ctx: MindContext, contextCount: number): boolean;
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
  *  The admission predicate recognition filters sites with (HOW_IT_WORKS
  *  §15.3): a form that leads nowhere contributes nothing to any derivation.

package/dist/src/mind/traverse.js

@@ -70,6 +70,29 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     const hit = memo?.get(id);
     if (hit !== undefined)
         return hit;
+    // BYTE-ATOM COMMONALITY.  A single-byte leaf (implicit negative id) has no
+    // structural parents BY CONSTRUCTION — atoms are never linked into the kid
+    // or contain tables — so this climb cannot observe its containment at all.
+    // The walk below would see only the atom's own direct edges and report
+    // contextsReached ≈ 1, turning the MOST common content in the store into
+    // the MOST discriminative voter (observed on a 325K-context store: every
+    // recognised single-letter site voted full ln N for the one fact whose
+    // continuation is that letter, and their pooled sum out-voted every
+    // genuine anchor).  An unmeasurable containment must not default to
+    // "maximally rare": it is bounded below by the uniform expectation over
+    // the byte alphabet — N contexts, each at least one chunk of up to W of
+    // the 256 possible atoms, reach ≥ N·W/256 contexts per atom on average
+    // (see {@link atomReach}).  When that floor itself exceeds the hub bound
+    // √N the atom is a hub at this corpus scale and the climb abstains
+    // (saturated) — the atom's own edges remain fully traversable (tier-0
+    // exact recall, chooseNext, project); only its say as a consensus voter
+    // is withdrawn.  On a small store the floor stays ≤ √N and the atom
+    // climbs exactly as before, so single-letter facts keep working.
+    if (id < 0 && atomIsHub(ctx, contextCount)) {
+        const reach = { roots: [], contextsReached: 0, saturated: true };
+        memo?.set(id, reach);
+        return reach;
+    }
     const bound = Math.ceil(Math.sqrt(contextCount));
     const roots = [];
     const seen = new Set([id]);
@@ -214,6 +237,24 @@ export function nextOf(ctx, id) {
 export function prevOf(ctx, id) {
     return ctx.store.prev(id);
 }
+/** The uniform-expectation floor on a byte atom's corpus commonality: N
+ *  learnt contexts, each at least one perception chunk of up to W of the 256
+ *  possible byte values, contain a given atom in ≥ N·W/256 contexts on
+ *  average.  An atom's TRUE containment is unmeasurable (atoms carry no
+ *  kid/contain links by construction), so this floor is the honest stand-in:
+ *  derived entirely from the corpus scale N, the perception window W, and
+ *  the alphabet size — never tuned. */
+export function atomReach(ctx, contextCount) {
+    return Math.max(1, Math.ceil((contextCount * ctx.space.maxGroup) / 256));
+}
+/** Whether a byte atom is a hub at this corpus scale — its commonality floor
+ *  {@link atomReach} exceeds the hub bound √N.  Below it (small stores) an
+ *  atom votes and is recognised exactly as any stored form; above it the
+ *  alphabet is scaffolding everywhere and abstains. */
+export function atomIsHub(ctx, contextCount) {
+    return atomReach(ctx, contextCount) >
+        Math.ceil(Math.sqrt(Math.max(2, contextCount)));
+}
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
  *  The admission predicate recognition filters sites with (HOW_IT_WORKS
  *  §15.3): a form that leads nowhere contributes nothing to any derivation.

package/dist/src/mind/types.d.ts

@@ -105,28 +105,40 @@ export interface MindContext extends GraphSearchHost {
     cfg: MindConfig;
     search: GraphSearch;
     trace: Rationale | null;
-    climbMemo: WeakMap<Uint8Array, Map<string, AttentionRead>> | null;
-    /** Per-response memo of {@link recognise} keyed by the byte-array OBJECT
-     *  (think, articulate, and the post-grounding pre-consume all recognise the
-     *  same query/answer objects).  Valid because the store is read-only while
-     *  a response is in flight; bypassed when a trace is attached so every
-     *  recognise still emits its rationale step.  Null outside respond(). */
-    recogniseMemo: WeakMap<Uint8Array, Recognition> | null;
-    /** Per-response memo of {@link perceive} keyed by the byte-array OBJECT —
-     *  the GENERAL memo the result-level ones (recogniseMemo, climbMemo,
-     *  _gistCache) each partially compensate for: resolve(), gistOf(), and
-     *  every mechanism's re-perception of the same query/answer object hit it
-     *  (a reason hop used to fold the same answer three times).  Valid because
-     *  the store is read-only while a response is in flight and perception is
-     *  a pure function of bytes; only inference-shaped calls (plain Uint8Array,
-     *  no leafAt/lookup capabilities) are memoised, so the deposit path never
-     *  sees it.  Keyed by CONTENT (latin1 of the bytes), not object identity —
-     *  mechanisms materialise the same span in fresh subarrays constantly
-     *  (measured on a trained store: 46% of one response's perceptions were
-     *  byte-identical repeats an identity key missed).  NOT bypassed under
-     *  trace — perception emits no rationale steps, so there is nothing a memo
-     *  hit could swallow.  Null outside respond(). */
+    /** The content canonicalizer for THIS response, or null — injected by the
+     *  modality entry point (respondText passes the text canonicalizer; a
+     *  binary respond passes none).  Resolution uses it as a fallback: when
+     *  the exact content-addressed lookup misses, the span's canonical key is
+     *  probed against the store's canon index (see src/canon.ts).  The core
+     *  never inspects what the equivalence IS. */
+    canon: ((bytes: Uint8Array) => Uint8Array) | null;
+    /** Per-response memo of canonical-fallback resolutions, keyed by the
+     *  span's latin1 content key.  Null outside respond(). */
+    canonMemo: Map<string, number | null> | null;
+    /** Memo of the consensus climb — content-keyed (latin1) so results
+     *  persist across conversation turns where the same byte spans recur.
+     *  Null outside respond(); during respondTurn() the conversation's
+     *  persistent map is swapped in. */
+    climbMemo: Map<string, Map<string, AttentionRead>> | null;
+    /** Memo of {@link recognise} — content-keyed (latin1) so recognised
+     *  forms carry forward across conversation turns.  Bypassed while a
+     *  trace is attached.  Null outside respond(). */
+    recogniseMemo: Map<string, Recognition> | null;
+    /** Memo of {@link perceive} — content-keyed (latin1).  The general
+     *  cache the result-level memos each partially compensate for.  NOT
+     *  bypassed under trace — perception emits no rationale steps.
+     *  Null outside respond(). */
     perceiveMemo: Map<string, Sema> | null;
+    /** Subtree-resolution cache: Sema node → its store id and byte length.
+     *  Populated by {@link foldTree} during inference; checked before
+     *  walking children.  When a conversation's pyramid reuses prefix
+     *  subtrees, this cache lets {@link recognise} skip them entirely —
+     *  O(suffix) instead of O(context).  Mind-lifetime (WeakMap keys are
+     *  the Sema objects the pyramid keeps alive). */
+    _resolvedSubtrees: WeakMap<Sema, {
+        id: number;
+        len: number;
+    }> | null;
     _edgeGuide: Vec | null;
     _edgeChoice: Map<number, number>;
     _prevSeen: Set<number> | null;

package/dist/src/store-sqlite.d.ts

@@ -43,6 +43,10 @@ export declare class SQliteStore extends AbstractStore implements Store {
     private _selPrev;
     private _setMeta;
     private _getMeta;
+    private _insCanon;
+    private _selCanon;
+    private _cntCanon;
+    private _selContentFrom;
     private _delMeta;
     private _insSnapshot;
     private _selSnapshot;
@@ -130,6 +134,10 @@ export declare class SQliteStore extends AbstractStore implements Store {
     protected _dbGetMeta(key: string): string | null;
     protected _dbSetMeta(key: string, val: string): void;
     protected _dbDeleteMeta(key: string): void;
+    canonAdd(h: number, id: number): void;
+    canonFind(h: number): number[];
+    canonCount(): number;
+    eachContent(cb: (id: number, bytes: Uint8Array) => void, fromId?: number): void;
     protected _dbSaveSnapshot(bytes: Uint8Array): void;
     protected _dbLoadSnapshot(): Uint8Array | null;
     protected _vecContentUpsert(entries: Array<{
@@ -144,6 +152,7 @@ export declare class SQliteStore extends AbstractStore implements Store {
     protected _vecContentSize(): number;
     protected _vecContentLastReads(): number;
     protected _vecContentPhysicalSize(): number;
+    protected _vecContentClusterCount(): number;
     protected _vecContentCompact(): void;
     protected _vecContentDeleteMany(ids: NodeId[]): void;
     protected _vecContentEntriesSince(after: number): IterableIterator<{
@@ -164,6 +173,7 @@ export declare class SQliteStore extends AbstractStore implements Store {
     }>;
     protected _vecHaloSize(): number;
     protected _vecHaloPhysicalSize(): number;
+    protected _vecHaloClusterCount(): number;
     protected _vecHaloCompact(): void;
     /** Pre-fill both vector indices' RAM caches with sequential scans (up to
      *  their budget caps) — seconds of streaming instead of the minutes of

package/dist/src/store-sqlite.js

@@ -112,6 +112,18 @@ CREATE TABLE IF NOT EXISTS contain (
   id      INTEGER PRIMARY KEY,
   parents BLOB NOT NULL
 );
+-- CANONICAL-FORM index (Store.canonAdd/canonFind): h is the 32-bit hash of a
+-- node's CANONICAL content key (the modality's canonicalizer output — case-
+-- folded, whitespace-collapsed text, etc.; the store never sees the key
+-- itself, only its hash).  Same hash-then-verify discipline as idx_node_h:
+-- the caller re-canonicalizes each candidate's bytes before trusting it, so
+-- a collision costs a read, never a wrong id.  WITHOUT ROWID on (h, id):
+-- the composite key IS the lookup index and gives free dedup.
+CREATE TABLE IF NOT EXISTS canon (
+  h  INTEGER NOT NULL,
+  id INTEGER NOT NULL,
+  PRIMARY KEY (h, id)
+) WITHOUT ROWID;
 CREATE TABLE IF NOT EXISTS snapshot (
   id INTEGER PRIMARY KEY CHECK (id = 1),
   data BLOB NOT NULL
@@ -212,6 +224,10 @@ export class SQliteStore extends AbstractStore {
     _selPrev = null;
     _setMeta = null;
     _getMeta = null;
+    _insCanon = null;
+    _selCanon = null;
+    _cntCanon = null;
+    _selContentFrom = null;
     _delMeta = null;
     _insSnapshot = null;
     _selSnapshot = null;
@@ -797,6 +813,42 @@ export class SQliteStore extends AbstractStore {
         }
         this._delMeta.run(key);
     }
+    // -- Canonical-form index (Store optional capability) --
+    canonAdd(h, id) {
+        if (!this._insCanon) {
+            this._insCanon = this.sqlite.prepare("INSERT OR IGNORE INTO canon (h, id) VALUES (?, ?)");
+        }
+        // Join the deferred write transaction (committed by flush/commit), so a
+        // bulk index build coalesces instead of paying autocommit per row.
+        this._dbBeginTx();
+        this._insCanon.run(h, id);
+    }
+    canonFind(h) {
+        if (!this._selCanon) {
+            this._selCanon = this.sqlite.prepare("SELECT id FROM canon WHERE h = ?");
+        }
+        return this._selCanon.all(h).map((r) => r.id);
+    }
+    canonCount() {
+        if (!this._cntCanon) {
+            this._cntCanon = this.sqlite.prepare("SELECT count(*) AS c FROM canon");
+        }
+        return this._cntCanon.get().c;
+    }
+    eachContent(cb, fromId = 0) {
+        if (!this._selContentFrom) {
+            // Content-bearing nodes are FLAT branches: leaf present, kids an
+            // empty (zero-length) blob — the same population PART 2 of the
+            // diagnostics calls "distinct content spans".
+            this._selContentFrom = this.sqlite.prepare("SELECT id, leaf FROM node " +
+                "WHERE id >= ? AND leaf IS NOT NULL " +
+                "AND (kids IS NULL OR length(kids) = 0)");
+        }
+        for (const row of this._selContentFrom.iterate(fromId)) {
+            const r = row;
+            cb(r.id, new Uint8Array(r.leaf));
+        }
+    }
     // -- Snapshot --
     _dbSaveSnapshot(bytes) {
         if (!this._insSnapshot) {
@@ -835,6 +887,9 @@ export class SQliteStore extends AbstractStore {
     _vecContentPhysicalSize() {
         return this.content ? this.content.physicalSize : 0;
     }
+    _vecContentClusterCount() {
+        return this.content ? this.content.clusterCount : 0;
+    }
     _vecContentCompact() {
         this.content.compact();
     }
@@ -869,6 +924,9 @@ export class SQliteStore extends AbstractStore {
     _vecHaloPhysicalSize() {
         return this.halos ? this.halos.physicalSize : 0;
     }
+    _vecHaloClusterCount() {
+        return this.halos ? this.halos.clusterCount : 0;
+    }
     _vecHaloCompact() {
         this.halos.compact();
     }

package/dist/src/store.d.ts

@@ -240,6 +240,18 @@ export interface Store {
      *  repetition, but repetition outranks insertion-order accident.  0 when
      *  the node has no halo row. */
     haloMass(id: NodeId): number;
+    /** Record that node `id`'s canonical key hashes to `h`.  Idempotent. */
+    canonAdd?(h: number, id: NodeId): void;
+    /** All candidate node ids whose canonical key hashes to `h` (collisions
+     *  included — the caller verifies). */
+    canonFind?(h: number): NodeId[];
+    /** Number of (h, id) rows in the canon index — 0 means never built. */
+    canonCount?(): number;
+    /** Visit every content-bearing node (flat branch: `leaf` present, no
+     *  kids) — the population a canonical index is built over.  `fromId`
+     *  restricts the scan to ids ≥ fromId, so an index refresh after further
+     *  training only visits the new rows. */
+    eachContent?(cb: (id: NodeId, bytes: Uint8Array) => void, fromId?: NodeId): void;
     size(): Promise<number>;
     saveSnapshot(bytes: Uint8Array): Promise<void>;
     loadSnapshot(): Promise<Uint8Array | null>;
@@ -336,6 +348,7 @@ export declare abstract class AbstractStore implements Store {
     protected abstract _vecContentSize(): number;
     protected abstract _vecContentLastReads(): number;
     protected abstract _vecContentPhysicalSize(): number;
+    protected abstract _vecContentClusterCount(): number;
     protected abstract _vecContentCompact(): void;
     /** Live content-index entries whose INTERNAL id is > `after`, as
      *  {ext, internal} pairs in internal-id order.  Internal ids are monotone
@@ -370,7 +383,17 @@ export declare abstract class AbstractStore implements Store {
      *  the tombstone-ratio compaction trigger compares physical size against. */
     protected abstract _vecHaloSize(): number;
     protected abstract _vecHaloPhysicalSize(): number;
+    protected abstract _vecHaloClusterCount(): number;
     protected abstract _vecHaloCompact(): void;
+    /** Derived query breadth for a partitioned index of C clusters: probe √C
+     *  of them (the same √-of-the-population convention as the hub bound √N).
+     *  The IVF maps ef → nprobe as ceil(ef/4), so ef = 4·⌈√C⌉ probes exactly
+     *  ⌈√C⌉ clusters.  A FIXED efSearch stops scaling the moment the
+     *  collection outgrows it: at 4,270 clusters the default 64 probed 16
+     *  clusters (0.4%), and an exact stored match of a query routinely sat in
+     *  an unprobed cluster — recall silently degraded as the store grew.  The
+     *  configured efSearch remains the floor for small collections. */
+    protected efFor(clusterCount: number): number;
     protected _D: number;
     protected _maxGroup: number;
     protected readonly minHaloMass: number;

package/dist/src/store.js

@@ -359,6 +359,17 @@ function haloDecode(blob, D) {
  * protected abstract methods that talk to the actual storage backend.
  */
 export class AbstractStore {
+    /** Derived query breadth for a partitioned index of C clusters: probe √C
+     *  of them (the same √-of-the-population convention as the hub bound √N).
+     *  The IVF maps ef → nprobe as ceil(ef/4), so ef = 4·⌈√C⌉ probes exactly
+     *  ⌈√C⌉ clusters.  A FIXED efSearch stops scaling the moment the
+     *  collection outgrows it: at 4,270 clusters the default 64 probed 16
+     *  clusters (0.4%), and an exact stored match of a query routinely sat in
+     *  an unprobed cluster — recall silently degraded as the store grew.  The
+     *  configured efSearch remains the floor for small collections. */
+    efFor(clusterCount) {
+        return Math.max(this.efSearch, 4 * Math.ceil(Math.sqrt(Math.max(1, clusterCount))));
+    }
     // ── Config ─────────────────────────────────────────────────────────────
     _D;
     _maxGroup;
@@ -1144,7 +1155,7 @@ export class AbstractStore {
             if (hit !== undefined)
                 return hit;
         }
-        const results = this._vecContentQuery(normalize(copy(v)), k * this.overfetch, this.efSearch);
+        const results = this._vecContentQuery(normalize(copy(v)), k * this.overfetch, this.efFor(this._vecContentClusterCount()));
         const out = [];
         for (const r of results) {
             const id = r.id;
@@ -1459,7 +1470,7 @@ export class AbstractStore {
             if (hit !== undefined)
                 return hit;
         }
-        const results = this._vecHaloQuery(normalize(copy(v)), k * this.overfetch, this.efSearch);
+        const results = this._vecHaloQuery(normalize(copy(v)), k * this.overfetch, this.efFor(this._vecHaloClusterCount()));
         const out = [];
         for (const r of results) {
             const id = r.id;

package/example/train_base.ts

@@ -177,8 +177,11 @@ const LOCAL_PATH = env("LOCAL_PATH", ""); // train from a local dir of *.zip
 const CACHE_DIR = env("CACHE_DIR", join(process.cwd(), "cache"));
 const MAX_CACHE_BYTES = Number(env("MAX_CACHE_GB", "100")) * 1e9;
 const PROGRESS_MS = Number(env("PROGRESS_MS", "250")); // panel refresh cadence
-// Index maintenance at checkpoints: compact (remove garbage) then repair (fill
-// gaps). Both are idempotent batch operations; INDEX_MAINTENANCE=0 disables.
+// Index maintenance at checkpoints: compact (remove garbage), repair (fill
+// gaps), then refresh the canonical-form index (equivalence-class resolution —
+// src/canon.ts). All three are idempotent batch operations (the canon build is
+// additionally incremental via the store's `canon.upto` cursor);
+// INDEX_MAINTENANCE=0 disables.
 const INDEX_MAINTENANCE = env("INDEX_MAINTENANCE", "1") !== "0";
 const DOWNLOAD_TRIES = 5;
 // In-progress downloads are written to a sibling "<dest>.part" and atomically
@@ -1823,11 +1826,25 @@ async function main(): Promise<void> {
 
   const checkpoint = () => mind.save();
 
-  /** Run index maintenance: compact (remove garbage) then repair (fill gaps).
-   *  Both are idempotent — running twice produces the same result as once.
-   *  Compaction frees index space first; repair then adds back the bridges
-   *  whose gists were evicted before indexing, completing the coverage that
-   *  incremental bridge promotion alone cannot guarantee.
+  /** Run index maintenance: compact (remove garbage), repair (fill gaps),
+   *  then refresh the canonical-form index (see below).  All three are
+   *  idempotent — running twice produces the same result as once.
+   *  Compaction frees index space first; repair then adds back every
+   *  edge/halo-bearing node whose gist was evicted from the pending cache
+   *  before it reached the content index, completing the coverage that
+   *  incremental promotion alone cannot guarantee.
+   *
+   *  repair runs with minParents = 0, NOT the library default of 2.  The
+   *  default repairs only structural BRIDGES (≥2 parents), but this
+   *  trainer's fact deposits also leave answer-side DEPOSIT ROOTS with 0
+   *  structural parents ("The capital of France is Paris." as the dst of a
+   *  Q→A edge is a root of its own tree, contained in nothing).  Those are
+   *  resonance targets recall depends on — a trained store shipped without
+   *  them cannot ground statement-shaped queries against its own answers
+   *  (observed: 33 such roots missing after a full curriculum, including
+   *  high-traffic conversation replies).  minParents = 0 admits every
+   *  edge/halo bearer; the candidate set is still corpus-of-experiences-
+   *  sized, so the pass stays cheap.
    *
    *  Logs the number of entries removed/added so a run that silently degrades
    *  (growing compaction count, or repair never recovering anything) is
@@ -1849,10 +1866,12 @@ async function main(): Promise<void> {
       );
     }
     try {
-      const added = await mind.repairContentIndex();
+      const added = await mind.repairContentIndex(0);
       if (added > 0) {
         progress.log(
-          `  ${GRN}index repair: added ${int(added)} missing bridges${R}`,
+          `  ${GRN}index repair: added ${
+            int(added)
+          } missing resonance targets${R}`,
         );
       }
     } catch (err) {
@@ -1862,6 +1881,27 @@ async function main(): Promise<void> {
         }`,
       );
     }
+    // Canonical-form index (src/canon.ts): lets resolution find stored forms
+    // across surface variation (case, width, whitespace).  Incremental and
+    // idempotent by construction — the `canon.upto` meta cursor scans only
+    // nodes newer than the last pass, and the (h, id) primary key ignores
+    // re-inserted rows — so it composes with the resume model exactly like
+    // compact/repair: every checkpoint (and finish) leaves the index
+    // covering all content trained so far.
+    try {
+      const added = await mind.buildCanonIndex();
+      if (added > 0) {
+        progress.log(
+          `  ${GRN}canon index: added ${int(added)} canonical-form entries${R}`,
+        );
+      }
+    } catch (err) {
+      progress.log(
+        `  ${YEL}⚠ canon index build failed${R}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
   };
 
   // The checkpoint recall is a best-effort diagnostic. It is time-bounded so a

package/index.html

@@ -52,6 +52,10 @@
         z-index: 0;
         overflow: hidden;
         background: var(--bg);
+        /* own stacking context + GPU layer: keeps the blend-mode orbs from
+           forcing full-page re-rasterization every frame on mobile */
+        isolation: isolate;
+        transform: translateZ(0);
       }
 
       /* — colour weather: two huge drifting orbs + aurora sweep — */
@@ -60,6 +64,7 @@
         border-radius: 50%;
         filter: blur(70px);
         mix-blend-mode: screen;
+        will-change: transform;
       }
       .orb.a {
         width: 75vmax;
@@ -130,6 +135,7 @@
           transparent 360deg
         );
         animation: spin 70s linear infinite;
+        will-change: transform;
       }
       @keyframes spin {
         to {
@@ -158,6 +164,7 @@
         );
         animation: drift 50s linear infinite alternate;
         opacity: 0.8;
+        will-change: transform;
       }
       @keyframes drift {
         to {
@@ -180,10 +187,12 @@
       .layerA {
         animation: sway 30s ease-in-out infinite alternate;
         transform-origin: 50% 50%;
+        will-change: transform;
       }
       .layerB {
         animation: sway 44s ease-in-out infinite alternate-reverse;
         transform-origin: 50% 50%;
+        will-change: transform;
       }
       @keyframes sway {
         from {
@@ -341,6 +350,7 @@
         opacity: 0.5;
         animation: spin 40s linear infinite;
         filter: drop-shadow(0 0 30px rgba(57, 230, 255, 0.3));
+        will-change: transform;
       }
       .hexring::before {
         content: "";
@@ -373,6 +383,7 @@
           transparent 70%
         );
         animation: breath 7s ease-in-out infinite;
+        will-change: transform, opacity;
       }
       @keyframes breath {
         0%, 100% {
@@ -423,6 +434,11 @@
         filter: drop-shadow(0 0 22px rgba(57, 230, 255, 0.35)) drop-shadow(
           0 8px 60px rgba(168, 120, 255, 0.25)
         );
+        /* gradient-clipped text flickers on iOS while its background animates
+           unless the element sits on its own composited layer */
+        -webkit-backface-visibility: hidden;
+        backface-visibility: hidden;
+        transform: translateZ(0);
       }
       @keyframes sheen {
         0%, 100% {
@@ -450,6 +466,7 @@
         color: transparent;
         -webkit-text-stroke: 1px rgba(57, 230, 255, 0.22);
         animation: echo 8s ease-in-out infinite;
+        will-change: transform, opacity;
       }
       @keyframes echo {
         0%, 100% {
@@ -594,6 +611,7 @@
         white-space: nowrap;
         width: max-content;
         animation: scroll 34s linear infinite;
+        will-change: transform;
       }
       .ticker span {
         padding: 0.72em 0;
@@ -652,6 +670,53 @@
         }
       }
 
+      /* ——————————————————— mobile / touch performance ——————————————————
+         Phones can't sustain the per-frame repaint work: SVG dash/scale
+         animations and background-position sheens repaint every frame, and
+         each pass runs through blur/drop-shadow filters. Strip the filters
+         and the repaint-driven animations; keep every compositor-friendly
+         transform/opacity animation so the page stays alive. */
+      @media (max-width: 820px), (pointer: coarse) {
+        .orb {
+          filter: blur(40px);
+        }
+        .aurora {
+          animation: none;
+        }
+        .grain {
+          display: none;
+        }
+        .wire,
+        .wire.v,
+        .wire.m,
+        .wire.g {
+          filter: none;
+          animation: none;
+          stroke-dasharray: none;
+          stroke-width: 1.2;
+          opacity: 0.75;
+        }
+        .layerA,
+        .layerB {
+          animation: none;
+        }
+        .ring {
+          animation-duration: 7s;
+        }
+        .hexring {
+          filter: none;
+        }
+        h1 {
+          animation: up 1s 0.2s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+          background-position: 35% 50%;
+          filter: drop-shadow(0 0 22px rgba(57, 230, 255, 0.35));
+        }
+        .btn.primary {
+          animation: none;
+          background-position: 50% 50%;
+        }
+      }
+
       /* ————————————————————————— reduced motion ———————————————————————— */
       @media (prefers-reduced-motion: reduce) {
         *, *::before, *::after {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "type": "module",
   "main": "dist/src/index.js",