From 49e4934e198ca018f4d593818fb60f3e26994cae Mon Sep 17 00:00:00 2001 From: Okiki Ojo Date: Fri, 22 May 2026 02:17:01 -0400 Subject: [PATCH] docs(guides): Clarify alignment cache and column semantics Update the internal codebase guide so it matches the runtime after the alignment work. The guide now explains that aligned-value memoization lives in a WeakMap instead of on the wrapper object, and that columnOffset measures UTF-16 insertion offset rather than indentation depth. This keeps future edits grounded in the current implementation and avoids reintroducing assumptions that were true before the unicode alignment changes. --- .agents/guides/codebase-patterns.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.agents/guides/codebase-patterns.md b/.agents/guides/codebase-patterns.md index a5548cf..0462fb4 100644 --- a/.agents/guides/codebase-patterns.md +++ b/.agents/guides/codebase-patterns.md @@ -79,10 +79,10 @@ entries) for repeated static snippets. ## `AlignedValue` per-value text cache -Each `AlignedValue` carries a small bounded cache stored as a non-enumerable -symbol property. It maps column positions to already-padded strings, so the -same value used repeatedly at the same insertion column avoids re-padding on -every call. Check `mod.ts` for the current cap. +Aligned values use a small bounded `WeakMap` cache keyed by wrapper object. +Each entry maps insertion pads to already-padded strings, so the same value +used repeatedly at the same insertion column avoids re-padding on every call +without mutating the public wrapper object. Check `mod.ts` for the current cap. ## Character code constants @@ -108,9 +108,9 @@ Hot scanning loops use integer character codes instead of string methods: ## `columnOffset` -Returns the number of leading whitespace characters (spaces + tabs) before -the first non-whitespace character on a line. Returns `Infinity` for -blank/whitespace-only lines (so they don't pull the minimum indent down). +Returns the number of UTF-16 code units after the last newline sequence in a +string. Alignment uses that insertion offset to decide how much padding to add +to subsequent lines. ## `TrimMode` and `TrimSides` -- 2.51.2