kireji 0.6.7 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "kireji",
- "version": "0.6.7",
+ "version": "0.7.3",
  "description": "A web framework for stateful, entropy-perfect, multi-origin web applications. Currently in alpha. Expect breaking changes for version 0. Use with caution!",
  "files": [
   "src/",

package/src/app/kireji/editor/point.js

@@ -163,7 +163,6 @@ const pointerConfig = {
      tabGroup.recomputeRouteID(true)
     } else {
 
-     debug("B", tabGroup.previewTabIndex === null, BigInt(tabGroup.openTabs.length), tabGroup.maxTabCount)
      if (BigInt(tabGroup.openTabs.length) === tabGroup.maxTabCount) {
       alert("You have too many tabs open!")
       return

package/src/app/kireji/editor/tab-group/type.d.ts

@@ -28,17 +28,11 @@ declare interface IKirejiAppTabGroup
  readonly permutationSizes: bigint[]
  readonly payloadCardinality: bigint
  readonly payloadSizes: bigint[]
- /** *Client-only*
-  * 
-  * The tab group's main HTML element. */
+ /** The tab group's main HTML element. @remarks Client-only */
  readonly container: HTMLElement
- /** *Client-only*
-  * 
-  * The most recent tab model, as determined while populating the view (not when propagating the route ID). */
+ /** The most recent tab model, as determined while populating the view (not when propagating the route ID). @remarks Client-only */
  readonly viewedActiveTab?: IKirejiAppTabGroupTab
- /** *Client-only*
-  * 
-  * The most recent preview tab model, as determined while populating the view (not when propagating the route ID). */
+ /** The most recent preview tab model, as determined while populating the view (not when propagating the route ID). @remarks Client-only */
  readonly viewedPreviewTab?: IKirejiAppTabGroupTab
  /** The most recent permutation route ID, used to quickly determine if the tab arrangement has changed since the last view population. */
  readonly viewedPermutationRouteID?: bigint
@@ -70,17 +64,11 @@ declare interface IKirejiAppTabGroupTab {
 }
 
 declare const tabGroup: IKirejiAppTabGroup
-/** The index of the tab to render.
- * 
- * *Only available in `close`, `point` and `renderTabHTML` methods.* */
+/** The index of the tab to render. @remarks Only in `close`, `point` and `renderTabHTML` methods. */
 declare const TAB_INDEX: number
-/** The host part of the given tab.
- * 
- * *Only available in `renderTabHTML` method.* */
+/** The host part of the given tab. @remarks Only in `renderTabHTML` method. */
 declare const TAB_PART: IPartAny
-/** The filename of the given tab.
- * 
- * *Only available in `renderTabHTML` method.* */
+/** The filename of the given tab. @remarks Only in `renderTabHTML` method. */
 declare const TAB_FILENAME: string
 declare const activeTab: IKirejiAppTabGroupTab
 declare const activePart: IPartAny

package/src/app/kireji/sidebar/type.d.ts

@@ -14,9 +14,7 @@ declare interface IKirejiAppSidebar
  readonly "view.html": string
  /** The part outliner currently assigned to the sidebar (resolves to a view even when the sidebar is hidden). */
  readonly "view": IPartOutliner<IKirejiAppSidebar>
- /** *Client Only*
-  * 
-  * Opens any closed parent folders of and scrolls (if necessary) to the element corresponding to the currently active tab. Does nothing if the sidebar is closed or there are no tabs open. */
+ /** Opens any closed parent folders of and scrolls (if necessary) to the element corresponding to the currently active tab. Does nothing if the sidebar is closed or there are no tabs open. @remarks Client-only */
  readonly frameActiveTab(): void
 
  // Runtime Properties.

package/src/build.js

@@ -90,6 +90,62 @@ function ƒ(_, compressedSubjectOrigins) {
      result[dimension] = vector[dimension] / magnitude
    return result
   }
+  static sign(vector) {
+   const result = {}
+   for (const dimension in vector)
+    result[dimension] = Math.sign(vector[dimension])
+   return result
+  }
+  static floor(vector) {
+   const result = {}
+   for (const dimension in vector)
+    result[dimension] = Math.floor(vector[dimension])
+   return result
+  }
+  static round(vector) {
+   const result = {}
+   for (const dimension in vector)
+    result[dimension] = Math.round(vector[dimension])
+   return result
+  }
+  static operate(value1, value2, operation) {
+   if (typeof value1 === "number" || typeof value2 === "number") {
+    if (typeof value1 === "number" && typeof value2 === "number")
+     return operation(value1, value2)
+
+    const result = {}
+    const number = typeof value1 === "number" ? value1 : value2
+    const vector = typeof value1 === "object" ? value1 : value2
+
+    for (const dimension in vector)
+     result[dimension] = operation(vector[dimension], number)
+
+    return result
+   }
+
+   const result = {}
+   const dimensions = Object.keys(value1)
+
+   if (dimensions.some(key => !(key in value2)) || Object.keys(value2).some(key => !(key in value1)))
+    throw new Error(`Vector Operation Error: the two vectors do not have the same keys.`)
+
+   for (const dimension of dimensions)
+    result[dimension] = operation(value1[dimension], value2[dimension])
+
+   return result
+  }
+  static add(value1, value2) {
+   return this.operate(value1, value2, (a, b) => a + b)
+  }
+  static subtract(value1, value2) {
+   return this.operate(value1, value2, (a, b) => a - b)
+  }
+  static multiply(value1, value2) {
+   return this.operate(value1, value2, (a, b) => a * b)
+  }
+  static dot(vector1, vector2) {
+   return vector1.x * vector2.x + vector1.y * vector2.y
+  }
  }
  class FenwickTree {
   static LSB = []

package/src/parts/abstract/mesh/build.js

@@ -0,0 +1,84 @@
+mesh.define({
+ triTable: { value: [] },
+ triIndex: { value: -1, writable: true },
+ position: { value: { x: null, y: null } },
+ cardinality: {
+  resolve() {
+   let meshCardinality = 0n
+
+   // Obtain the raw data for this mesh.
+   const [pointList, tris] = mesh.getData()
+
+   // Iterate over each tri (array of three point indices) in the data.
+   for (const tri of tris) {
+
+    // Prepare the per-tri cardinality sum.
+    let triCardinality = 0n
+
+    // Recover the true points of the tri.
+    const points = tri.map(pointID => pointList[pointID])
+
+    // Get just the y-coordinate of all the points.
+    const yPoints = points.map(point => point[1])
+
+    // Estimate the y-range of this tri.
+    const range = {
+     min: Math.min(...yPoints),
+     max: Math.max(...yPoints)
+    }
+
+    // Iterate over the range inclusively to populate each row subspace.
+    const rows = []
+    for (let rowID = range.min; rowID <= range.max; rowID++) {
+
+     // This irrational offset ensures that all grid points lie vertically in at most one triangular region.
+     const offsetRowID = rowID + (Math.PI / 3.141 - 0.5)
+
+     // Iterate over the 3 lines in order to determine where the edges intersect the given row.
+     const intersections = []
+     for (let edgeID = 0; edgeID < 3; edgeID++) {
+
+      const pointA = points[edgeID]
+      const pointB = points[(edgeID + 1) % 3]
+
+      if ((pointA[1] <= offsetRowID && pointB[1] > offsetRowID) || (pointB[1] <= offsetRowID && pointA[1] > offsetRowID))
+       intersections.push(pointA[0] + ((offsetRowID - pointA[1]) / (pointB[1] - pointA[1])) * (pointB[0] - pointA[0]))
+     }
+
+     if (intersections.length < 2) {
+      // This row doesn't have a full pixel. Adjust the range.
+      if (rowID <= range.min + 1) range.min = rowID + 1
+      else if (rowID >= range.max - 1) range.max = rowID - 1
+      else throw new Error("Unexpected tri geometry found in mesh.")
+      continue
+     }
+
+     /** @type {IMeshTriDataRow} */
+     const row = {
+      y: rowID,
+      range: {
+       min: Math.ceil(Math.min(...intersections)),
+       max: Math.ceil(Math.max(...intersections)) - 1,
+      },
+      offset: triCardinality
+     }
+     rows.push(row)
+     triCardinality += BigInt(row.range.max - row.range.min + 1)
+    }
+
+    // Store the tri.
+    mesh.triTable.push({
+     points,
+     range,
+     rows,
+     offset: meshCardinality,
+     cardinality: triCardinality
+    })
+
+    meshCardinality += triCardinality
+   }
+
+   return meshCardinality
+  }
+ }
+})

package/src/parts/abstract/mesh/constants.js

@@ -0,0 +1 @@
+const mesh = this

package/src/parts/abstract/mesh/model_.js

@@ -0,0 +1 @@
+return { ...mesh.position }

package/src/parts/abstract/mesh/part.json

@@ -0,0 +1,18 @@
+{
+ "abstract": true,
+ "methods": {
+  "data-get": [],
+  "point-tri-contains": [
+   "TRI_INDEX",
+   "POINT"
+  ],
+  "point-tri-that-contains": [
+   "POINT"
+  ],
+  "ray-cast": [
+   "FORCE_VECTOR",
+   "DELTA_TIME",
+   "ENABLE_SLIDING"
+  ]
+ }
+}

package/src/parts/abstract/mesh/point-tri-contains.js

@@ -0,0 +1,14 @@
+const roundedY = Math.floor(POINT.y)
+const triData = mesh.triTable[TRI_INDEX]
+
+if (roundedY < triData.range.min || roundedY > triData.range.max)
+ return false
+
+const row = triData.rows[roundedY - triData.range.min]
+
+if (!row)
+ return false
+
+const roundedX = Math.floor(POINT.x)
+
+return roundedX >= row.range.min && roundedX <= row.range.max

package/src/parts/abstract/mesh/point-tri-that-contains.js

@@ -0,0 +1,10 @@
+// Check current tri first.
+if (mesh.triIndex !== -1 && mesh.triContainsPoint(mesh.triIndex, POINT))
+ return mesh.triIndex
+
+// Check all tris. TODO: Memoize neighbors.
+for (let triIndex = 0; triIndex < mesh.triTable.length; triIndex++)
+ if (triIndex !== mesh.triIndex && mesh.triContainsPoint(triIndex, POINT))
+  return triIndex
+
+return -1

package/src/parts/abstract/mesh/ray-cast.js

@@ -0,0 +1,262 @@
+// Define a safe result: the current position before casting.
+const safeIterationResult = {
+ hit: false,
+ triIndex: mesh.triIndex,
+ point: { ...mesh.position },
+ forceVector: FORCE_VECTOR
+}
+
+// Obtain the speed of the force vector, which will be used later if we need to slide along the boundary.
+const speed = Vector.magnitude(FORCE_VECTOR)
+
+// If there's no motion, nothing will happen; return the safe result.
+if (speed === 0)
+ return safeIterationResult
+
+// Otherwise, initialize timing data as though the vector doesn't intersect any grid lines.
+const timeOfNextIntersection = { x: Infinity, y: Infinity }
+const timeBetweenIntersections = { ...timeOfNextIntersection }
+
+// Set the clock to zero.
+let time = 0
+
+function initalizeRayIntersectionSchedule(alsoComputeIntersectionInterval) {
+
+ // If the force vector isn't parallel to the x axis...
+ if (FORCE_VECTOR.x !== 0) {
+
+  // Determine the x coordinate of the first grid line the ray may intersect.
+  const nextGridX = Math.floor(safeIterationResult.point.x) + (FORCE_VECTOR.x > 0)
+
+  // Compute the exact moment that intersection will happen.
+  timeOfNextIntersection.x = time + (nextGridX - safeIterationResult.point.x) / FORCE_VECTOR.x
+
+  // Compute the constant time between each grid line intersection.
+  if (alsoComputeIntersectionInterval)
+   timeBetweenIntersections.x = 1 / Math.abs(FORCE_VECTOR.x)
+ }
+
+ // Perform the same steps for the y-axis.
+ if (FORCE_VECTOR.y !== 0) {
+  const nextGridY = Math.floor(safeIterationResult.point.y) + (FORCE_VECTOR.y > 0)
+  timeOfNextIntersection.y = time + (nextGridY - safeIterationResult.point.y) / FORCE_VECTOR.y
+  if (alsoComputeIntersectionInterval)
+   timeBetweenIntersections.y = 1 / Math.abs(FORCE_VECTOR.y)
+ }
+}
+
+initalizeRayIntersectionSchedule(true)
+
+const start = _.now
+
+let iteration = 0
+
+// Start iterating on the ray cast.
+while (true) {
+
+ iteration++
+
+ // Emergency exit the loop.
+ if (_.now - start >= (DELTA_TIME * 1000))
+  throw { error: "LOCKED WHILE LOOP", processingTime: _.now - start, iteration, DELTA_TIME, FORCE_VECTOR, speed, safeIterationResult, timeOfNextIntersection, timeBetweenIntersections }
+
+ // Pick the dimension whose grid intersection will happen next.
+ const dimension = timeOfNextIntersection.x < timeOfNextIntersection.y ? "x" : "y"
+
+ // Note how much time must elapse to reach that intersection.
+ let timeElapsedDuringThisIteration = timeOfNextIntersection[dimension] - time
+
+ // Set the clock to the moment of that intersection.
+ time += timeElapsedDuringThisIteration
+
+ // Note if this is a case where the grid intersection is reached after the time limit.
+ let ranOutOfTime = time >= DELTA_TIME
+
+ // In that case...
+ if (ranOutOfTime) {
+
+  // Measure how far we are past the time limit.
+  const overshootTime = time - DELTA_TIME
+
+  // Adjust how much time we say elapsed.
+  timeElapsedDuringThisIteration -= overshootTime
+
+  // Set the block back to the last possible moment.
+  time = DELTA_TIME
+ }
+
+ // Construct the next point along the ray, given the elapsed time.
+ const point = Vector.add(safeIterationResult.point, Vector.multiply(FORCE_VECTOR, timeElapsedDuringThisIteration))
+
+ // Check if the point is outside the mesh boundary.
+ const triIndex = mesh.triThatContainsPoint(point)
+
+ // If it is...
+ if (triIndex === -1) {
+
+  // We are at a boundary pixel. Let's move our position to exactly the center of our current point.
+  // safeIterationResult.point = Vector.add(Vector.floor(safeIterationResult.point), 0.5)
+
+  // If we have permission to simulate sliding...
+  if (ENABLE_SLIDING) {
+
+   // Walk back the clock to before the ray hit.
+   time -= timeElapsedDuringThisIteration
+
+   const neighbor = {
+    dot: -Infinity,
+    point: null,
+    triIndex: null,
+    direction: {
+     x: null,
+     y: null
+    }
+   }
+
+   let boundaryAppearsFlat = false
+
+   // Search the local neighborhood of points for one that we can safely move to.
+   for (let x = -1; x <= 1; x++) for (let y = -1; y <= 1; y++) {
+
+    // Exclude the point itself
+    if (!x && !y)
+     continue
+
+    const direction = { x, y }
+
+    // Find out how much of the force vector is cancelled out by going to this neighbor.
+    const dot = Vector.dot(Vector.normalize(direction), Vector.normalize(FORCE_VECTOR))
+
+    // If it would require traveling "against" or perpendicular to the force vector, exclude it from consideration.
+    if (dot < 0)
+     continue
+
+    // Get the position of the center of the neighbor.
+    const point = Vector.add(Vector.floor(Vector.add(safeIterationResult.point, direction)), 0.5)
+    const triIndex = mesh.triThatContainsPoint(point)
+
+    // If it isn't part of the mesh, exclude it from consideration.
+    if (triIndex === -1)
+     continue
+
+    // Store the neighbor which most agrees with the force vector.
+    if (dot >= neighbor.dot) {
+     if (dot < 0.05 && neighbor.dot !== -Infinity && neighbor.dot < 0.05) {
+      boundaryAppearsFlat = true
+      // Boundary is "flat". Don't allow perpendicular motion.
+      neighbor.dot = -Infinity
+      neighbor.point = null
+      neighbor.triIndex = null
+      neighbor.direction.x = null
+      neighbor.direction.y = null
+     } else {
+      boundaryAppearsFlat = false
+      neighbor.dot = dot
+      neighbor.point = point
+      neighbor.triIndex = triIndex
+      neighbor.direction = direction
+     }
+    }
+   }
+
+   if (boundaryAppearsFlat) {
+    // TODO: Consider using the line through the opposing neighbors to search for assymetry in the mesh boundry.
+   }
+
+   // If there is no neighboring point, we are "stuck". The ray cast ends here.
+   if (!neighbor.point) {
+
+    // Return the safe result data.
+    safeIterationResult.hit = true
+    return safeIterationResult
+   }
+
+   // Compute travel distance to the center of the neighbor.
+   const vectorToNeighbor = Vector.subtract(neighbor.point, safeIterationResult.point)
+   const distance = Vector.magnitude(vectorToNeighbor)
+
+   // Construct a force vector pointing to the chosen neighbor.
+   // TODO: speed should actually be reduced.
+   const forceVectorToNeighbor = Vector.multiply(Vector.normalize(vectorToNeighbor), speed)
+
+   // Compute travel time to reach the neighbor.
+   timeElapsedDuringThisIteration = distance / speed
+
+   // Move the clock ahead to our arrival at the neighbor.
+   time += timeElapsedDuringThisIteration
+
+   // Check again if we ran out of time.
+   ranOutOfTime = time >= DELTA_TIME
+   if (ranOutOfTime) {
+    const overshootTime = time - DELTA_TIME
+    timeElapsedDuringThisIteration -= overshootTime
+    time = DELTA_TIME
+
+    // Construct the point along the way to the neighbor.
+    const point = Vector.add(safeIterationResult.point, Vector.multiply(forceVectorToNeighbor, timeElapsedDuringThisIteration))
+    const triIndex = mesh.triThatContainsPoint(point)
+    safeIterationResult.forceVector = forceVectorToNeighbor
+
+    if (triIndex === -1) {
+     // We didn't have enough time to overcome the diagonal boundary.
+
+     if (speed * DELTA_TIME > Math.SQRT2) {
+      // The current speed is enough to overcome diagonal corners.
+
+      // Return the previous safe point, chalking the lost time up to friction.
+      return safeIterationResult
+     }
+
+     // There is not enough velocity to overcome the diagonal. Use random chance.
+     if (Math.random() < Math.SQRT1_2) {
+      safeIterationResult.point = neighbor.point
+      safeIterationResult.triIndex = neighbor.triIndex
+     }
+
+     return safeIterationResult
+    } else {
+
+     // Go to the partial point.
+     safeIterationResult.point = point
+     safeIterationResult.triIndex = triIndex
+    }
+
+    return safeIterationResult
+
+    // TODO: Consider moving toward a 4-point neighbor instead.
+   }
+
+   // Set the neighbor as the new safe point.
+   safeIterationResult.point = neighbor.point
+   safeIterationResult.triIndex = neighbor.triIndex
+   safeIterationResult.forceVector = FORCE_VECTOR
+
+   // The normal ray intersection schedule has changed.
+   initalizeRayIntersectionSchedule()
+
+   // Proceed with normal ray casting behavior from this point.
+   continue
+
+  } else {
+
+   // Discard the unsafe point and return the safe result data.
+   safeIterationResult.hit = true
+   return safeIterationResult
+  }
+ }
+
+
+ // Otherwise, update the safe result.
+ safeIterationResult.point = point
+ safeIterationResult.triIndex = triIndex
+
+ // If we ran out of time...
+ if (ranOutOfTime) {
+
+  // We're done. Return the safe point.
+  return safeIterationResult
+ }
+
+ // Otherwise, Prepare for the next grid line time of this dimension.
+ timeOfNextIntersection[dimension] += timeBetweenIntersections[dimension]
+}

package/src/parts/abstract/mesh/routeID-distribute.js

@@ -0,0 +1,42 @@
+mesh.updateRouteID(ROUTE_ID)
+
+// Binary search better than embedded match.
+mesh.triIndex = (() => {
+
+ let low = 0
+ let high = mesh.triTable.length - 1
+
+ while (low <= high) {
+
+  const mid = (low + high) >>> 1
+  const triData = mesh.triTable[mid]
+  const nextTriData = mesh.triTable[mid + 1]
+
+  if (ROUTE_ID < triData.offset)
+   high = mid - 1
+  else if (nextTriData && ROUTE_ID >= nextTriData.offset)
+   low = mid + 1
+  else
+   return mid
+ }
+
+ // Fallback.
+ return 0
+})()
+
+ROUTE_ID -= mesh.triTable[mesh.triIndex].offset
+
+// Embedded match can become binary search later.
+for (const row of mesh.triTable[mesh.triIndex].rows) {
+
+ if (!row)
+  continue
+
+ const rowWidth = BigInt(row.range.max - row.range.min + 1)
+
+ if (ROUTE_ID < row.offset + rowWidth) {
+  mesh.position.y = row.y
+  mesh.position.x = row.range.min + Number(ROUTE_ID - row.offset)
+  break
+ }
+}

package/src/parts/abstract/mesh/routeID-model-to.js

@@ -0,0 +1,5 @@
+// TODO: Validate MODEL and handle out-of-range points.
+const triIndex = mesh.triThatContainsPoint(MODEL)
+const triData = mesh.triTable[triIndex]
+const row = triData.rows[Math.floor(MODEL.y) - triData.range.min]
+return triData.offset + row.offset + BigInt(Math.floor(MODEL.x) - row.range.min)

package/src/parts/abstract/mesh/type.d.ts

@@ -0,0 +1,85 @@
+declare interface IMesh<TOwner>
+ extends IPart<TOwner, null> {
+
+ // Serialized Properties.
+ readonly getData(): IMeshData
+ /** Casts a ray from the current mesh position along the force vector direction for the given delta time and returns a summary of the results. @param FORCE_VECTOR the force vector represent the position the uninterrupted ray will arrive at in one second. @param DELTA_TIME the duration of the time cast in seconds. @param ENABLE_SLIDING whether or not to enable the ray to "wrap" along the mesh boundary instead of stopping cold. */
+ readonly castRay(FORCE_VECTOR: IVector2, DELTA_TIME: number, ENABLE_SLIDING: boolean): {
+  /** Whether or not the ray hit the mesh boundary. */
+  readonly hit: boolean
+  /** The tri the ray most recently occupied when it hit the boundary or the index of the boundary where the ray stopped if there is no hit. */
+  readonly triIndex: IMeshTriIndex
+  /** The rounded cell position where the cast ray landed. */
+  readonly position: IVector2
+  /** The force vector used to cast the ray, which might be different from the input if sliding is enabled as it may point along the direction of the most recent sliding iteration. */
+  readonly forceVector: IVector2
+ }
+ /** Checks if a point (x, y) rounds to a valid pixel within the specified tri's memoized row data. */
+ readonly triContainsPoint(TRI_INDEX: IMeshTriIndex, POINT: IVector2): boolean
+ /** Returns whether or not the given point is in a tri. @returns the index of the tri that contains the point. -1 otherwise. */
+ readonly triThatContainsPoint(POINT: IVector2): IMeshTriIndex
+
+ // Runtime Properties.
+ /** The memoization data of every tri in the mesh, stored by tri index at build-time. */
+ readonly triTable: IMeshTriData[]
+ /** The index of the current tri in the mesh. */
+ readonly triIndex?: IMeshTriIndex
+ /** The current position of the state in the mesh. */
+ readonly position: IVector2
+}
+
+declare interface IMeshTriData {
+ /** The original point array of the tri as taken from `mesh.getData()`. */
+ readonly points: IMeshTriPoints
+ /** The y-axis range of the tri. */
+ readonly range: {
+  /** The y position of the top-most row of the tri. */
+  readonly min: number
+  /** The y position of the bottom-most row of the tri. */
+  readonly max: number
+ }
+ /** The rows of pixels in the tri. */
+ readonly rows: IMeshTriDataRow[]
+ /** The offset of the tri in the overall mesh. */
+ readonly offset: bigint
+ /** The total number of pixels in the tri. */
+ readonly cardinality: bigint
+}
+
+declare interface IMeshTriDataRow {
+ /** The y position of this row of the tri's space. */
+ readonly y: number
+ /** The x-axis range of the row. */
+ readonly range: {
+  /** The smallest x position that is within the tri row. */
+  readonly min: number
+  /** The largest x position that is within the tri row. */
+  readonly max: number
+ }
+ /** The bigint offset of this row in the overall tri. */
+ readonly offset: bigint
+}
+
+declare type IMeshData = [IMeshPoint[], IMeshTri[]]
+
+declare type IMeshTri =
+ [IMeshPointIndex, IMeshPointIndex, IMeshPointIndex]
+
+declare type IMeshPointIndex =
+ number
+
+declare type IMeshTriPoints =
+ [IMeshPoint, IMeshPoint, IMeshPoint]
+
+declare type IMeshPoint =
+ [x: number, y: number]
+
+declare type IMeshTriIndex =
+ number
+
+declare type IMeshAny =
+ IMesh<IPartAny>
+
+declare const mesh: IMeshAny
+
+declare const TRI: IMeshTriData

package/src/parts/abstract/part/part.json

@@ -65,9 +65,7 @@
    "IMAGE_NAME"
   ],
   "loop-distribute": [],
-  "loop": [
-   "TIME"
-  ],
+  "loop": [],
   "attr-point": [
    "METHOD_NAME = 'point'",
    "...ARGS"

package/src/parts/abstract/part/routeID-update.js

@@ -1,14 +1,14 @@
 if (part.isAbstract)
- throw new Error(`You can't set the route ID of an abstract part. (${part.host})`)
+ throw new Error(`Route ID Update Error: You can't set the route ID of an abstract part. (${part.host})`)
 
 if (ROUTE_ID === undefined)
- throw new Error(`The ROUTE_ID argument is missing. ` + part.host)
+ throw new Error(`Route ID Update Error: The ROUTE_ID argument is missing. ` + part.host)
 
 if (typeof ROUTE_ID !== "bigint" || ROUTE_ID < -1n)
- throw new Error(`Route ID is invalid. ` + part.host)
+ throw new Error(`Route ID Update Error: Route ID is invalid. ` + part.host)
 
 if (ROUTE_ID >= part.cardinality)
- throw new Error(`Route ID (${ROUTE_ID}) out of range (max = ${part.cardinality - 1n}). ` + part.host)
+ throw new Error(`Route ID Update Error: Route ID (${ROUTE_ID}) out of range (max = ${part.cardinality - 1n}). ` + part.host)
 
 part.previousRouteID = part.routeID
 part.routeID = ROUTE_ID
@@ -20,6 +20,6 @@ part.justDisabled = !part.enabled && part.wasEnabled
 part.deltaRouteID = part.routeID - part.previousRouteID
 
 if (part.deltaRouteID === 0n)
- warn(`Reassigned route ID (${part.routeID}) to part.\n ${part[".."] ? `${part[".."].key} {\n  ${part.key} : "${part.host}" // <--- this part \n }` : part.host}`)
+ warn(`Route ID Update Warning: Reassigned route ID (${part.routeID}) to part.\n ${part[".."] ? `${part[".."].key} {\n  ${part.key} : "${part.host}" // <--- this part \n }` : part.host}`)
 
 part.dirty = true

package/src/parts/abstract/part/type.d.ts

@@ -43,7 +43,7 @@ declare interface IPart<TOwner, TSubpart>
  readonly notify(EVENT_TYPE: string): void
  /** Computes the cardinality of the part from its subparts and defines any other necessary properties. */
  readonly build(): void
- /** Calls loop on the part and then propagates the call leafward to all subparts. */
+ /** Calls `loop()` on the part and then propagates the call leafward to all subparts. */
  readonly distributeLoop(): void
  /** Returns the subparts that meet the condition provided by FILTER_FUNCTION.  */
  readonly filter(FILTER_FUNCTION: (subpart: TSubpart, index: number, part: IPart<TOwner, TSubpart>) => TSubpart): TSubpart[]
@@ -53,7 +53,7 @@ declare interface IPart<TOwner, TSubpart>
  readonly includes(SUBPART: TSubpart): boolean
  readonly reduce(REDUCE_FUNCTION: (result: TResult, subpart: TSubpart, index: number, part: IPart<TOwner, TSubpart>) => TResult, INITIAL_VALUE: TResult): TResult
  /** If defined, the per-frame update method for the part. Useful for implementing game features. */
- readonly loop?(TIME: DOMHighResTimeStamp): void
+ readonly loop?(): void
  /** Performs MAP_FUNCTION on every subpart of the part and returns an array of the results. */
  readonly map(MAP_FUNCTION: (subpart: TSubpart, index: number, part: IPart<TOwner, TSubpart>) => TResult): TResult[]
  /** Converts the given model to a routeID without modifying the state of the part. */
@@ -158,9 +158,7 @@ declare interface IPart<TOwner, TSubpart>
  /** The previous route of the part, changed at the last call to distributeRouteID or collectRouteID. */
  readonly previousRouteID: bigint
  readonly Property: typeof Property
- /** The part's prototype part.
-  * 
-  * *Note: The part `part.abstract.parts` does not have a prototype part.* */
+ /** The part's prototype part. @remarks The part `part.abstract.parts` does not have a prototype part. */
  readonly prototype?: IPartAny
  /** The current route of the part expressed as a bigint index in the virtual array of all of its routes. */
  readonly routeID: bigint
@@ -227,13 +225,9 @@ declare function base(...args): any
 declare function recurse(...args): any
 /** Sets the current ecosystem route ID and host application as the undo point (the state the back button will return to). */
 declare function setUndoPoint(): void
-/** The current incoming route ID argument.
- * 
- * *Available within distributeRouteID, setRouteID and updateRouteID methods only.*  */
+/** The current incoming route ID argument. @remarks Available within distributeRouteID, setRouteID and updateRouteID methods only. */
 declare const ROUTE_ID: bigint
-/** The part on which an event occurred.*
- * 
- * **where available as an argument passed to a part listener callback.* */
+/** The part on which an event occurred. @remarks Where available as an argument passed to a part listener callback. */
 declare const SENDER: IPartAny
 /** If on the client, returns whether or not the server-rendered view has been taken over by the client-side MVC framework. */
 declare const hydrated: boolean | null

package/src/parts/abstract/permutation/type.d.ts

@@ -33,24 +33,16 @@ declare interface IPermutation<TOwner, TInstance, TModel, TSubject>
  readonly supersetSize: bigint
  /** The maximum number of instances that can exist at one time. */
  readonly maxInstanceCount: bigint
-
  /** A subindex representing which permutation of k instances is assigned. */
  readonly permutationRouteID: bigint
- /** *Client-only*
-  * 
-  * The most recent permutation route ID, used to quickly determine if the instance arrangement has changed since the last view population. */
+ /** The most recent permutation route ID, used to quickly determine if the instance arrangement has changed since the last view population. @remarks Client-only */
  readonly viewedPermutationRouteID?: bigint
-
  /** A subindex representing the combined per-instance payload data for the k instances. */
  readonly payloadRouteID: bigint
-
  /** The distributed instance data. */
  readonly instances: TInstance[]
- /** *Client-only*
-  * 
-  * The set of viewed instance objects corresponding to the current `part.viewedPermutationRouteID`. */
+ /** The set of viewed instance objects corresponding to the current `part.viewedPermutationRouteID`. @remarks Client-only */
  readonly viewedInstances: TInstance[]
-
  /** A Fenwick tree that allows performant ranking and unranking of permutation indices. */
  readonly tree: FenwickTree
 }

package/src/parts/core/client/async-install.js

@@ -3,91 +3,82 @@ await Promise.all([
  worker.takeControlAsync()
 ])
 
-logScope(0, "Finalizing Hydration", log => {
- if (+_.haltHydration && !production)
-  warn('Intentionally blocked hydration.')
- else {
-
-  // To preview FOUC
-  if (_.hangHydration > 0 && !production)
-   logScope(0, `Intentionally hanging the main thread for ${_.hangHydration} milliseconds.`, log => {
-    const start = _.now
-    let iteration = -1, elapsedMilliseconds, remainingMilliseconds
-    do {
-     elapsedMilliseconds = Math.trunc(_.now - start)
-     const newRemainingMilliseconds = _.hangHydration - elapsedMilliseconds
-     Math.sin(iteration++)
-     if (Math.trunc(newRemainingMilliseconds / 100) !== Math.trunc(remainingMilliseconds / 100))
-      log("t: -" + newRemainingMilliseconds)
-     remainingMilliseconds = newRemainingMilliseconds
-    } while (remainingMilliseconds > 0)
-    log(`Main thread hang finished at iteration ${iteration}.`)
-   })
-
-  log("Defining Client-Only Methods, Globals and Default Listeners")
-  if (environment === "client") {
-   Object.assign(globalThis, {
-    Q(...args) {
-     return document.querySelector(...args)
-    },
-    inRect(pointerEvent, boundingClientRect) {
-     return pointerEvent.clientX >= boundingClientRect.left
-      && pointerEvent.clientX <= boundingClientRect.right
-      && pointerEvent.clientY >= boundingClientRect.top
-      && pointerEvent.clientY <= boundingClientRect.bottom
-    },
-    setUndoPoint() {
-     _.parts.core.addressBar.setUndoPoint()
-    },
-    pointer: _.parts.core.pointer,
-    client: _.parts.core.client
-   })
+if (!production) {
 
-   // Clean up preview operations upon going back.
-   // TODO: fix bugs here.
-   window.addEventListener("pageshow", pageTransitionEvent => {
-    log("Setting Initial State")
-    addressBar.useRoute()
-
-    log("Activating Body")
-    document.body.classList.remove("unhydrated")
+ // To debug FOUC.
+ if (+_.haltHydration) {
+  warn('Intentionally blocked hydration.')
+  return
+ }
 
-    debug('remove these preview classes', document.querySelectorAll(`[class^="preview-"]`))
-   })
+ // To simulate slow loading time.
+ if (+_.hangHydration > 0) {
+  warn(`Intentionally hanging the main thread for ${_.hangHydration} milliseconds.`)
+  const start = _.now
+  while (_.hangHydration - (_.now - start) > 0)
+   Math.sin(Math.random())
+ }
+}
 
-   // Prevent normal click events to ensure the pointerdown event always takes precedence.
-   document.addEventListener("click", pointerEvent => {
-    pointerEvent.preventDefault()
-    pointerEvent.stopPropagation()
-   }, { capture: true })
+logScope(0, "Finalizing Hydration", log => {
 
-   // Listen for history popstate, which is called if bfcache is not employed.
-   globalThis.addEventListener("popstate", () => {
-    log("Setting Initial State")
-    addressBar.useRoute()
+ log("Defining Client-Only Methods, Globals and Default Listeners")
+ Object.assign(globalThis, {
+  Q(...args) {
+   return document.querySelector(...args)
+  },
+  inRect(pointerEvent, boundingClientRect) {
+   return pointerEvent.clientX >= boundingClientRect.left
+    && pointerEvent.clientX <= boundingClientRect.right
+    && pointerEvent.clientY >= boundingClientRect.top
+    && pointerEvent.clientY <= boundingClientRect.bottom
+  },
+  setUndoPoint() {
+   _.parts.core.addressBar.setUndoPoint()
+  },
+  pointer: _.parts.core.pointer,
+  client: _.parts.core.client
+ })
 
-    log("Activating Body")
-    document.body.classList.remove("unhydrated")
+ // Handle navigation. TODO: fix bugs here.
+ window.addEventListener("pageshow", pageTransitionEvent => {
+  log("Setting Initial State")
+  addressBar.useRoute()
 
-    debug('remove these preview classes', document.querySelectorAll(`[class^="preview-"]`))
-   })
-  }
+  log("Activating Body")
+  document.body.classList.remove("unhydrated")
 
+  debug('remove these preview classes', document.querySelectorAll(`[class^="preview-"]`))
+ })
+ globalThis.addEventListener("popstate", () => {
   log("Setting Initial State")
   addressBar.useRoute()
 
   log("Activating Body")
   document.body.classList.remove("unhydrated")
 
-  // Make ecosystem available to HTML event handlers.
-  globalThis._ = _
+  debug('remove these preview classes', document.querySelectorAll(`[class^="preview-"]`))
+ })
 
-  log("Starting Engine Loop")
-  _.define({
-   frameRequest: { value: requestAnimationFrame(() => _.distributeLoop()), writable: true },
-  })
+ // Prevent normal click events to ensure the pointerdown event always takes precedence.
+ document.addEventListener("click", pointerEvent => {
+  pointerEvent.preventDefault()
+  pointerEvent.stopPropagation()
+ }, { capture: true })
 
-  log("Client hydration complete.")
-  client.hydrated = true
- }
+ log("Setting Initial State")
+ // Propagate the initial state (matched to the snapshot exactly).
+ addressBar.useRoute()
+
+ log("Activating Interaction")
+ // Enable HTML event listeners.
+ globalThis._ = _
+ // Disable pre-hydration presentation.
+ document.body.classList.remove("unhydrated")
+ // Switch to post-hydration state propagation.
+ client.hydrated = true
+
+ log("Starting Engine Loop")
+ // One-frame lag to capture refresh-rate-specific initial timestamp.
+ requestAnimationFrame(now => client.requestLoop(now))
 })

package/src/parts/core/client/build.js

@@ -1,3 +1,7 @@
-facet.define({
- hydrated: { value: false, writable: true }
+client.define({
+ hydrated: { value: false, writable: true },
+ fps: { value: 60, writable: true },
+ now: { value: null, writable: true },
+ deltaTime: { value: null, writable: true },
+ meanFrameTime: { value: 1000 / 60, writable: true },
 })

package/src/parts/core/client/loop-request.js

@@ -0,0 +1,10 @@
+requestAnimationFrame(now => {
+ const deltaTime = now - REQUEST_TIME
+ // Use 60fps delta if returning to tab or heavy lag.
+ client.deltaTime = deltaTime > 100 ? (1000 / 60) : deltaTime
+ client.meanFrameTime += (client.deltaTime - client.meanFrameTime) / 20
+ client.fps = Math.round(1000 / client.meanFrameTime)
+ client.now = now
+ _.distributeLoop()
+ recurse(now)
+})

package/src/parts/core/client/part.json

@@ -1,3 +1,8 @@
 {
- "extends": "facet"
+ "extends": "facet",
+ "methods": {
+  "loop-request": [
+   "REQUEST_TIME"
+  ]
+ }
 }

package/src/parts/core/client/type.d.ts

@@ -1,10 +1,24 @@
 declare interface IClient
  extends IFacet<ICore> {
 
+ // Serialized Properties.
+ /** Requests an animation frame that distributes the loop function throughout the ecosystem and calls itself again. @remarks Can only be run on the client. */
+ readonly requestLoop(REQUEST_TIME: DOMHighResTimeStamp): void
+
  // Runtime Properties.
- /** Whether or not the server-rendered page has been fully "taken over" by the client-side framework. */
+ /** Whether or not the server-rendered page has been fully "taken over" by the client-side framework. @remarks Can only become true in the client environment. */
  readonly hydrated: boolean
+ /** The averaged framerate of the application over a certain time window. @remarks Defaults to `60` before the first loop and when not in the client environment. */
+ readonly fps?: number
+ /** The current session time, aligned to the client refresh rate by `requestAnimationFrame`. @remarks Defaults to 'null' on first loop and when not in the client environment.*/
+ readonly now: number
+ /** The difference between the session time of the current frame and the session time of the previous frame. @remarks Defaults to `1000 / 60` before the first loop and when not in the client environment. */
+ readonly deltaTime: number
+ /** The average length of time each frame is on screen in milliseconds. @remarks Defaults to `1000 / 60` before the first loop and when not in the client environment. */
+ readonly meanFrameTime?: number
 }
 
-/** A facet which helps toggle the page style between a locked loading state (before hydration) and a fully-interactive state (after hydration). */
-declare const client: IClient
+/** A facet which helps toggle the page style between a locked loading state (before hydration) and a fully-interactive state (after hydration). It also starts and continues the engine loop. */
+declare const client: IClient
+/** The animation frame timestamp when the method was called. @remarks Only available in `client.requestLoop()`. */
+declare const REQUEST_TIME: DOMHighResTimeStamp

package/src/parts/core/hot-keys/async-install.js

@@ -37,6 +37,7 @@ globalThis.addEventListener("keyup", keyboardEvent => {
 })
 
 globalThis.addEventListener("keydown", keyboardEvent => {
+
  if (!keyboardEvent.repeat) {
   /* This handles the edge case when the user is holding modifier keys that
    * they pressed while not focused on this instance of the ecosystem. */
@@ -64,15 +65,24 @@ globalThis.addEventListener("keydown", keyboardEvent => {
 
   hotKeys.pressed.add(keyboardEvent.code)
 
-  const combo = hotKeys.combo
-  const methodName = JSON.parse(_.application["hot-keys.json"] ?? "{}")[combo] ?? hotKeys.table[combo]
-  const method = methodName && (_.application[methodName] ?? hotKeys[methodName])
+  const doCombo = () => {
+   const combo = hotKeys.combo
+   const methodName = JSON.parse(_.application["hot-keys.json"] ?? "{}")[combo] ?? hotKeys.table[combo]
+   const method = methodName && (_.application[methodName] ?? hotKeys[methodName])
 
-  if (methodName) {
-   keyboardEvent.preventDefault()
-   if (typeof method === "function")
-    method()
-   // else warn(`Hot Keys Warning: method called ${methodName} is not defined on either the hot keys manager or the current application.`)
+   if (methodName) {
+    keyboardEvent.preventDefault()
+    if (typeof method === "function")
+     method()
+    // else warn(`Hot Keys Warning: method called ${methodName} is not defined on either the hot keys manager or the current application.`)
+   }
   }
+
+  // Prevent a bug when the user presses keys too early.
+  if (client.hydrated)
+   doCombo()
+  else
+   client.promise.then(doCombo)
+
  }
 })

package/src/parts/core/hot-keys/constants.js

@@ -1,2 +1,4 @@
-const agent = _.parts.core.agent
-const hotKeys = this
+const hotKeys = this
+const core = hotKeys[".."]
+const agent = core.agent
+const client = core.client

package/src/parts/core/pointer/type.d.ts

@@ -36,13 +36,9 @@ declare interface IPointerConfig {
  doubleClick: (pointerEvent: PointerEvent) => void,
  /** The action that should finally execute whenever the user's pointer action is complete (whether successfully or through a native pointer event cancellation). */
  reset: () => void,
- /** **REQUIRED**
-  * 
-  * The pointerdown event responsible for launching the pointer session. */
+ /** The pointerdown event responsible for launching the pointer session. @remarks Required for all pointer handling. */
  readonly POINTER_EVENT: PointerEvent,
- /** **REQUIRED**
-  * 
-  * The target HTML element whose pointerdown listener responsible for launching the pointer session. */
+ /** The target HTML element whose pointerdown listener responsible for launching the pointer session. @remarks Required for all pointer handling. */
  readonly TARGET_ELEMENT: HTMLElement,
  /** Optional helper that can automate calling TARGET_ELEMENT.focus() during the pointer session. */
  readonly focus?: "none" | "down" | "click",
@@ -51,11 +47,7 @@ declare interface IPointerConfig {
 declare const pointer: IPointer
 
 declare const POINTER_CONFIG: IPointerConfig
-/** The pointerdown event that the current listener is reacting to.
- * 
- * *Available only in pointerdown event listeners.* */
+/** The pointerdown event that the current listener is reacting to. @remarks Only in pointerdown event listeners. */
 declare const POINTER_EVENT: PointerEvent
-/** The element that the current pointerdown event is reacting to.
- * 
- * *Available only in pointerdown event listeners.* */
+/** The element that the current pointerdown event is reacting to. @remarks Only in pointerdown event listeners. */
 declare const TARGET_ELEMENT: HTMLElement

package/src/parts/desktop/task-bar/tray/stats/button.html_.js

@@ -1 +1,4 @@
-return stats.fps
+if (environment === "client")
+ return client.fps
+
+return 60

package/src/parts/desktop/task-bar/tray/stats/loop.js

@@ -1,3 +1 @@
-stats.fps = Math.round(1000 / (stats.meanFrameTime += (TIME - (stats.mark ?? TIME) - stats.meanFrameTime) / 20))
-stats.mark = TIME
-stats.element.textContent = stats.fps
+stats.element.textContent = client.fps

package/src/parts/desktop/task-bar/tray/stats/type.d.ts

@@ -1,13 +1,6 @@
 declare interface IStats
  extends ITrayItem {
 
- // Runtime Properties.
- /** If in the client environment, the computed framerate of the application. Null otherwise. */
- readonly fps?: number
- /** If in the client environment, the time (taken from _.now) of the last loop evaluation. Null otherwise. */
- readonly mark?: DOMHighResTimeStamp
- /** If in the client environment, the average length of time each frame is on screen in milliseconds. Null otherwise. */
- readonly meanFrameTime?: number
 }
 
 /** The framerate monitor, which sits in the taskbar tray. */

package/src/parts/desktop/windows/type.d.ts

@@ -23,9 +23,7 @@ declare interface IDesktopWindowModel {
  readonly height: number
 }
 
-/** The host of the application to render.
- * 
- * *Only available in `renderTaskHTML` methods.* */
+/** The host of the application to render. @remarks Only in `renderTaskHTML` methods. */
 declare const APPLICATION_HOST: string
 declare const INSTANCES: IDesktopWindow[]
 declare const INSTANCE: IDesktopWindow

package/src/type.d.ts

@@ -50,9 +50,7 @@ declare interface IEcosystem
  readonly setRoute(REQUEST_URL: string): void
  /** Performs automated build-time unit tests to validate the state of the build. */
  readonly validate(): void
- /** *Client-only*
-  * 
-  * Navigates to the given host by setting the current location. An undo point is automatically set by the browser. */
+ /** Navigates to the given host by setting the current location. An undo point is automatically set by the browser. @remarks Client-only */
  readonly gotoApplication(HOST: string): void
 
  // Runtime Properties.
@@ -68,15 +66,11 @@ declare interface IEcosystem
  readonly landingModel: string
  /** The routeID of the desired landing page, as computed from data parameters during the initial boot process. */
  readonly landingRouteID: bigint
- /** If in the client environment, an integer ID representing the application frame loop's current pending frame request. Null, otherwise. */
- readonly frameRequest: number | null
  /** A boolean that is set to `true` as soon as the route ID is set for the first time. */
  readonly initialized: undefined | true
 }
 
-/** The root part. When JSON stringified, it should inline all information compiled from the git repo in node by the build process.
- * 
- * The serialized version should not include any values that are added during or after recursively hydrating the part tree. */
+/** This is the root part of the ecosystem, considered the ecosystem itself. @remarks When JSON stringified, it should inline all information compiled from the git repo in node by the build process. The serialized version should not include any values that are added during or after recursively hydrating the part tree. This means that all runtime values should be non-enumerable and defined using the `define()` method. */
 declare const _: IEcosystem
 /** A shorthand for document.querySelector */
 declare const Q: typeof document.querySelector
@@ -261,9 +255,7 @@ declare class MethodConstant {
  /** Idempotent function that ensures that the constant and all its recursive dependencies (`requirements`) are declared (added to the source file output). Marks the constant as used. */
  ensureDeclarationAndDependencies(): void
 }
-/** The incoming request url string.
- * 
- * Available only in _.setRoute(). */
+/** The incoming request url string. @remarks Only in _.setRoute(). */
 declare const REQUEST_URL: string
 /** A host-keyed map of all parts in the ecosystem. */
 declare const partsByHost: Record<string, IPartAny>
@@ -316,6 +308,18 @@ declare class FenwickTree {
 declare class Vector {
  static magnitude(vector: IVector): number
  static normalize(vector: IVector): IVector
+ static sign(vector: IVector): IVector
+ static floor(vector: IVector): IVector
+ /** Performs the given binary operation on the two values, which can each be either a vector or a number. If at least one of the values is a vector, returns a vector. Otherwise, returns a number. */
+ static operate(value1: IVector | number, value2: IVector | number, operation: (a, b) => number): IVector | number
+ /** Adds the two values, which can each be either a vector or a number. If at least one of the values is a vector, returns a vector. Otherwise, returns a number. */
+ static add(value1: IVector | number, value2: IVector | number): IVector | number
+ /** Subtracts the two values, which can each be either a vector or a number. If at least one of the values is a vector, returns a vector. Otherwise, returns a number. */
+ static subtract(value1: IVector | number, value2: IVector | number): IVector | number
+ /** Multiplies the two values, which can each be either a vector or a number. If at least one of the values is a vector, returns a vector. Otherwise, returns a number. */
+ static multiply(value1: IVector | number, value2: IVector | number): IVector | number
+ static dot(vector1: IVector, vector2: IVector): number
 }
 
-declare type IVector = Record<string, number>
+declare type IVector = Record<string, number>
+declare type IVector2 = { x: number, y: number }

package/src/loop-distribute.js

@@ -1,2 +0,0 @@
-base()
-_.frameRequest = requestAnimationFrame(() => _.distributeLoop(_.now))

package/src/parts/desktop/task-bar/tray/stats/build.js

@@ -1,5 +0,0 @@
-stats.define({
- fps: { value: 60, writable: true },
- mark: { value: null, writable: true },
- meanFrameTime: { value: 1000 / 60, writable: true }
-})