kireji 0.6.7 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "kireji",
- "version": "0.6.7",
+ "version": "0.6.8",
  "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/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/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/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/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>

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 }
-})